= This is a small tutorial for those who want to contribute to Frugalware == Ways of contributing There are many different ways to contribute to Frugalware. You can write documentation, translate the existing documentation into your native language (or any other language you want to), maintain packages or improve them with added features etc. If you are a programmer you can help us in developing our applications. These are: pacman-g2, gfpm, fwlive, frugalwareutils, setup etc. See http://git.frugalware.org[git.frugalware.org] for different project repositories. You can also start new projects. If you show some code we can surely host your project too if it's Frugalware related. For example you want to write kfpm :) IMPORTANT: After each title in brackets you can find the target audience. === Translations (translators) You can read the details on our link:translations.html[Translations] documentation page. === Necessary documentation (packagers, coders) In the first part I will cover the information necessary for those who do _not_ have developer status yet. In the second part we will set up the necessary config files. First of all, we ask you to read the following documentation carefully. If you do not want to deal with packages, but just want to code it's usually enough to read the git documentation as we store our code in git repositories. * man makepkg * man pacman-g2 * man repoman * man FrugalBuild * man fwmakepkg * http://frugalware.org/docs/makepkg[makepkg howto] * http://www.kernel.org/pub/software/scm/git/docs/everyday.html[git getting started] I know, it is boring reading documentation, but you have to know that writing it is even worse so do not ask questions when the answer in the documentation. If you can not understand something feel free to join #frugalware@irc.freenode.net and ask. === Downloading and setting up the repositories ==== Getting the frugalware-current repo (packagers) The frugalware-current repo is the development repo for the packages. When you want to get it you need the git package. Let's get it: -------------------- # pacman-g2 -S git -------------------- Now create a git directory where you can hold all your repos. You can choose any other name of course. ------------------ $ mkdir -p ~/git $ cd ~/git ------------------ Now clone the repo with git: -------------------------------------------------------------------------------------------------------------- $ git clone http://frugalware.org/git/pub/frugalware/frugalware-current current $ cd current -------------------------------------------------------------------------------------------------------------- Now be patient while git clones all the objects and then checks out the files. Also you can use other mirrors as well. ==== Getting pacman-g2 and other code (coders) First of all you need the repo of the program. In this example I will use pacman-g2, but the steps are very similar. NOTE: Most of our programs need the translations repo to compile) --------------------------------------------------------------------- $ mkdir -p ~/git $ cd ~/git $ git clone http://frugalware.org/git/pub/other/translations (optional) $ git clone http://frugalware.org/git/pub/other/pacman-g2/pacman-g2 $ cd pacman-g2 --------------------------------------------------------------------- ==== Setting up the repository and sending patch via email (packagers, coders) Now you should setup up your identity. -------------------------------------------------------- $ git config --global user.name "Your Name" $ git config --global user.email email@addr.ess $ git config branch.master.rebase true -------------------------------------------------------- Now you can make your changes. When finished run ------------ $ git diff ------------ in the repository. TIP: You can also use 'git diff .' (note the dot in the end). In that case git will show the changes recursively in the current directory. It is very handy when you have lot of uncommitted changes in your repo. If you are satisfied with the changes run -------------- $ git commit -a -------------- to commit all your changes. If you want to cherry-pick hunks from your changes: ---- $ dg record ---- or using native git commands: ---- $ git add -p; git commit ---- Without committing your changes you can not send nor push (just developers) it. TIP: With frugalware-* repos it's recommended to use 'repoman rec' which is a wrapper for dg record. It sets up the patch name properly so you only need to deal with the details. NOTE: http://www.tpope.net/node/106[Here] you can find more details on how to write good commit messages in general using git. Here comes the final step. Send in the patch(es)! ------------ $ git format-patch $ git send-email --to frugalware-devel@frugalware.org . ------------ `` is the `sha1` of the last patch you do 'not' want to submit. Run ---- $ git log ---- and you'll see the hash. Also, you can just use your existing mail client and send the patch(es) as an attachment. If everything goes fine your patch should show up on the http://frugalware.org/mailman/listinfo/frugalware-devel[frugalware-devel] mailing list soon. NOTE: You have to subscribe to the http://frugalware.org/mailman/listinfo/frugalware-devel[frugalware-devel] mailing list and set up your SMTP server properly (if you use `git send-email`). It doesn't really belong to here but I want to document it somewhere. If you are a developer and want to apply such a patch, you need: - Check the patch itself. If the second line is not an empty one, then you need to hand-edit the patch before applying: ---- Subject: [PATCH] powwow-1.2.13-1-i686 * new package ---- to: ---- Subject: [PATCH] powwow-1.2.13-1-i686 * new package ---- - Then you can apply the patch using git-am: ---- $ cat 0002-powwow-1.2.13-1-i686.patch | git am ---- You should do this in the root directory of the repository. === Further options for those who have developer account (packagers, coders) Once you get a developer account, you have the right to request the following services: * BTS access (so that we can assign tasks to you) * git write access (you'll always get this, except if you are working on the artwork or so) * a @frugalware.org mail address (with imaps/pop3s access) * Public and private devspace. The first is in the `/pub/other/people/nick` dir and this is mirrored (you must not put private stuff to there). The later is your `~/public_html` dir: it is not mirrored and there is no backup for it. Though you may temporarily put private stuff to there. * a @frugalware.org jabber account if you want one What you should do: * You should read the frugalware-devel mailing list. When you're asked, please try to respond. * If you push patches to git, you should subscribe to the frugalware-git mailing list. This is list has a big traffic since a new mail is sent for each patch. If you don't have time to read it, subscribe then set the "I would like to receive no mail" option. Also take care that your subscribing email address is the same one you set using `git config user.email` * It's good if you can join the user and developer channel when you're online. * Maintain your packages. Try to resolve your assigned bugs, try to keep your packages up to date, and if you needed patches for packages, send them upstream. If you don't have anything to do for a week that's usually a bad sign. It's - of course - OK when you go for vacation a few times a year, but then please announce it on the developer mailing list so that we won't wait for you when fixing urgent problems, etc. * Document your work. The documentation is worth nothing if it's outdated. Ideally somone who has never contacted us should be able to understand every detail of Frugalware, just from documentation. No secrets! We are not kids. * If you have time, try to read the mailing lists ( `frugalware-users*@` ) and the forums. If you prefer reading the forums from your mail client, there is a bi-directional gateway on the `frugalware-forums@` list, use it. Let us see what you should set up to get it work. I will also give some tips which can make your life easier. Read http://wiki.frugalware.org/index.php/Git_setup[this page], we collected a set of tricks when we converted from darcs to git. ==== Setting up the frugalware-* repos and repoman (packagers) It is time to set up some necessary things. We start with the frugalware-current repo. Make sure that you are in the root of the frugalware-current repo. Also do not forget to change the username to your login name on git.frugalware.org. ---- $ git config remote.origin.url 'username@git.frugalware.org:/home/ftp/pub/frugalware/frugalware-current' $ git config remote.origin.receivepack "sudo -u repo git-receive-pack" ---- As you will use `repoman` to upload the packages (and many other things as you'll see) we should set it up now. This step is also necessary. Open '~/.repoman.conf' with your favourite editor and add the following lines: ---- fst_root=~/git current_servers=("username@git.frugalware.org:/home/ftp/pub/frugalware/frugalware-current") stable_servers=("username@git.frugalware.org:/home/ftp/pub/frugalware/frugalware-stable") stable_pushonly="y" ---- Where fst_root is the directory where you store your git repos. Username is your login on git.frugalware.org. For details see `man repoman`. As from now use the following command from package's directory to push your changes. -------------- $ repoman push -------------- It will check the FrugalBuild using fblint, then record your changes, push them, upload the fpms and finally create the changelog, update the fdb etc. So you are done if there was no error message. ==== Setting up other repos (coders) In repo's main directory: ------------------------------------------------------------------------------------------------------------- $ git config remote.origin.url 'username@git.frugalware.org:/home/ftp/pub/other/pacman-g2/pacman-g2' $ git config remote.origin.receivepack "sudo -u owner git-receive-pack" ------------------------------------------------------------------------------------------------------------- Do not forget to change the username and repository path. For paths refer to the http://git.frugalware.org/[gitweb] interface. NOTE: The owner for `pacman-g2`, `frugalwareutils`, `pacman-tools` is usually `vmiklos`. You should always review what you would push before you perform the action: ---- $ git fetch $ git rebase origin/master $ git log origin/master..master ---- Then you can use ------------ $ git push ------------ to send in your changes. NOTE: The `dg push` wrapper does exactly this for you.