User:Pytony/How to contribute code

From Funtoo
Jump to: navigation, search

How to contribute code

__NOTITLE__

   Warning

This page is not the official guide to development. It is a proposal to improve the current How to Dev page.

Figure out which repository to contribute.

The first thing to do, when you want to improve an ebuild or submit one, is to figure out in which git repository you should work.

New ebuilds

If you want to submit a new ebuild, there are two possibilities:

  1. If you have your own overlay or wish to create one to actively maintain the ebuilds you will submit, create your ebuild in this overlay. We will be able to merge individual ebuilds from your overlay into Funtoo kits and allow you to submit new versions and patches without requiring manual validation on our side for each new commit. This has the advantage of providing you full control on ebuilds you maintain, but also, this makes you fully responsible of this ebuild maintenance.
  2. Alternatively, if you don't want to create your own overlay or don't want to be the only one liable for ebuild maintenance, you can submit new ebuilds to flora, our user-contributed overlay. This has the drawback to require manual validation on our side for each commit, but the advantage to allow other contributors to bump versions, fix errors and apply patches.

Improve existing ebuilds

Finding where an existing ebuild comes from might be more tricky than it looks like. Indeed, it is very tempting to assume that if an ebuild is in python-kit (for instance), you will be able to submit a pull request to https://github.com/funtoo/python-kit. However, this doesn't work like that, we won't be able to merge pull requests on such repositories. Indeed, these repositories are automatically generated from various repositories and any manual commit would be overridden by the next update.

So how to figure out in which repository you'll have to work? For this, you can use ego query origin tool. This will give you the name of the repository as well as the URL to browse or clone the repository:

user $ ego query origin app-editors/vim
app-editors/vim::editors-kit comes from fusion809
        https://github.com/fusion809/fusion809-overlay/tree/master/app-editors/vim
        https://gitweb.gentoo.org/repo/gentoo.git/tree/app-editors/vim
user $ ego query origin docker-compose
app-emulation/docker-compose::nokit comes from gentoo-staging
        http://git.funtoo.org/gentoo-staging/tree/app-emulation/docker-compose
        https://gitweb.gentoo.org/repo/gentoo.git/tree/app-emulation/docker-compose
user $ ego query origin brave-bin
www-client/brave-bin::net-kit comes from flora
        https://github.com/funtoo/flora/tree/master/www-client/brave-bin
user $ ego query origin app-admin/ego::core-kit
app-admin/ego::core-kit comes from kit-fixups
        https://github.com/funtoo/kit-fixups/tree/master/core-kit/global/app-admin/ego

If the ebuild comes from gentoo-staging, it means it was not forked in Funtoo. Thus you should fork it in kit-fixups.

Repository Main URL Github Mirror
flora git://git.funtoo.org:flora.git https://github.com/funtoo/flora/
kit-fixups git://git.funtoo.org:kits/kit-fixups.git https://github.com/funtoo/kit-fixups/

Once you have figured out which repository you will work on, clone it:

user $ cd ~/Workspace/Funtoo  # or wherever your store you Funtoo contributing stuff
user $ git clone https://github.com/funtoo/kit-fixups.git  # Or whatever relevant repository

Before starting to work, it is a good idea to create a new branch dedicated to the changes you will do. This will simplify the process of creating a patch to submit (see below). If you work on an existing issue on bugs.funtoo.org, you can name your branch after the issue number for instance, but you are absolutely free to name it as you wish.

user $ git checkout -b FL-1664  # Create a new branch named "FL-1664"

Forking an ebuild

If the ebuild you want to improve, comes from Gentoo (origin is gentoo-staging), you will have to copy the existing package hierarchy to kit-fixups.

First, check out which kit the ebuild belongs:

user $ ego query versions dev-python/cython
 dev-python/cython| slot|                 repo
------------------+-----+---------------------
              0.22|    0| python-kit/3.6-prime
            0.24.1|     | python-kit/3.6-prime
          * 0.25.2|     | python-kit/3.6-prime
              0.26|     | python-kit/3.6-prime

Ther repo column will give which kit each version belongs as well as the branch the kit is on. Some versions might also come from third-party overlays if you have installed third-party overlays. So, in this example, dev-python/cython is in python-kit kit, on branch 3.6-prime. Here are the steps to fork the ebuild, assuming you are currently in the kit-fixups git repository:

user $ mkdir -pv python-kit/3.6-prime/dev-python/cython
user $ cd python-kit/3.6-prime/dev-python/cython
user $ cp -rv /var/git/meta-repo/kits/python-kit/dev-python/cython/* .
user $ sed -i '1{/^# Copyright/d}' *.ebuild  # Remove copyright line from ebuilds
user $ sed -i 's/^\(\s*KEYWORDS\)=".*"/\1="*"/' *.ebuild  # Funtoo doesn't use KEYWORDS

If all branches of the kit need to be fixed, use the special directory global instead of 3.6-prime in the above example.

Now you can do whatever you need on ebuilds.

Testing your changes

To make sure that your ebuild will be fetched, compiled and installed properly (at least on your machine), you can emerge it using ebuild command:

root # ebuild cython-0.26.ebuild merge

To sanitize your environment after that, you can update world and perform a depclean:

root # emerge -avuDN @world
root # emerge -ac

Committing your changes

Once you are satisfied with your changes, you can commit them. You will obviously not be able to push your commit(s), but you will be able to create a patch:

user $ git format-patch 3.6-prime --stdout > FL-1664_fix_something.patch

Here you have your patch that you can attach to the issue you were working on, or attach to the issue you will create if none already exist. We will be able to apply it using the following command to properly credit you:

user $ git am --signoff < FL-1664_fix_something.patch