= 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 ones to your native language (or any other language you want to) maintain packages or making them better whith adding features whatever. 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 necessary informations 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 documentations carefully. If you do not want to deal with packages, 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 them is even worse so do not ask questions when there is 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 git://git.frugalware.org/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 git://git.frugalware.org/pub/other/translations (optional) $ git clone git://git.frugalware.org/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 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. 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`). Not really belongs 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) * voice on the #frugalware.dev channel * 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 equals to the 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 yourself. The documentation worth nothing if it's outdated. Ideally one who never contacted use 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/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 vmiklos git-receive-pack" ------------------------------------------------------------------------------------------------------------- IMPORTANT: Do not edit the second line! So that `vmiklos` have to be `vmiklos`. It's because he is the current owner of that repo. 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 records your changes, pushes them, uploads the fpms and finally creates the changelog, updates 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.