Gentoo GitHub

From Gentoo Wiki
(Redirected from Gentoo Github)
Jump to: navigation, search

This article explains how to contribute to Gentoo by creating pull requests on GitHub.

Thank you for helping the Gentoo project and considering sending a Pull Request via GitHub! Contributions are always welcome and highly appreciated.

Before hitting the "Create pull request" button on GitHub, we would like to remind you a few rules to facilitate the process as much as possible and have your contribution quickly accepted.

We won't accept pull requests which do not follow these guidelines and will remind you about them in the pull request.

How to make a pull request

Making a pull request is explained at length in the various how-tos put together by the GitHub folks, here are two must-read how-tos:

Adding a new package to Gentoo

First file a bug prior to filing a pull request for a new package. Why? we need to make sure your email address is recorded in Bugzilla as you will be maintaining the package in question and assigned arising bug reports. Commits introducing new packages need a lot more details than normal commits. Please provide a lengthy message in the body of the commit message as your commit will appear in the ChangeLog file and detail what is the package's purpose as much as possible and not just "new package". See for instance.

New means there is no older version in the tree yet.
Currently new packages are added via proxy-maint project and the current manpower isn't enough to handle the flood of new packages. We recommend contributing to GURU overlay instead for now, where interesting and popular packages are pulled to ::gentoo. Read more:

Usage of repoman

We strongly encourage the use of the app-portage/repoman utility which performs various QA checks against ebuilds, as well as updates the manifest and pre-formats a commit message for you. One of the first checks done on an ebuild is to verify it with the command

user $repoman -dx full

so you should at least run this before committing. You can also use repoman to make commits using

user $repoman -dx commit

When using repoman, run it from the lowest point in the repository possible (as in, within the ebuild directory) otherwise it may try checking all ebuilds below the current directory.

Signing commits

GnuPG Key verification (verified)

Repoman can sign git commits by using app-crypt/gnupg, which then can be verified by While gentoo developers still need to check and verify the pull requests, it helps securing another part of the ebuilds way into the tree. The signing can be set up in two steps:

Configure Git

Set up git to automatically sign your commits and set the PORTAGE_GPG_DIR environment variable to point at your ~/.gnupg (or similar) before running repoman.

user $cd <repository>
user $git config --local "Your Full Name"
user $git config --local "example@domain.tld"
user $git config --local user.signingkey "Your GPG signingkey"
user $git config --local commit.gpgsign true
Upload the public key to GitHub

Last thing needed is to upload the public GnuPG key to This can be done under Settings -> SSH and GPG keys.

That’s all. The next commit you push as described in the beginning will be verified by GitHub and you will see a neat green, little box saying “verified”.

Possible issues with signing

It's possible that you get hit by a message like

user $error: gpg failed to sign the data

fatal: failed to write commit object

!!! Exiting on git (shell) error code: 128

In such a case you want to make sure your GPG_TTY environment variable is set. To make sure it is always set, you can add it to your ${HOME}/.bashrc or to /etc/portage/make.conf:

FILE ${HOME}/.bashrc
export GPG_TTY=$(tty)

Setting pinentry to a terminal-friendly variant, like pinentry-ncurses or pinentry-tty might also help with this issue. You can list the available pinentry variants with

user $eselect pinentry list

Available pinentry binary implementations:

 [1]   pinentry-qt
 [2]   pinentry-qt4
 [3]   pinentry-curses
 [4]   pinentry-tty *

and set the desired one with

user $eselect pinentry set [number]

For further information about gpg, please visit to the GnuPG page.

Commit format

Commits must respect a special format. If you've already taken a look at the repository log, most commits begin with "CATEGORY/PN: some message". We expect you to format your commits the same way. As you will be using repoman to make your commit, it should already preformat the commit message for you. However, if you are making a commit to a file which is not an ebuild, please take a look at this link: Commit message format.

Manifest files

If your pull request bumps a package, commit the updated Manifest file along with all your changes. If you don't, Larry the Cow (our QA bot) will flag up errors across the various checks performed. If you receive an UnnecessaryManifest error from the QA bot, it's most likely due to not using repoman and copying the Manifest file from a repository that doesn't use thin manifests.

Separate (or "atomic") commits

Avoid big, fat, massive commits. If your PR involves a version bump as well as cleaning up an old version and modifying the metadata.xml file, do commit these three changes separately. We need to go back in time in case something goes wrong and therefore, having separate commits for each and every change happening in the repository is the only way to achieve that.

Rebasing commits

Sometimes you may be asked to squash or rebase commits into one. This is usually required when there are multiple commits that belong to a single logical change e.g. version bumps. Make sure to read the following page that explains at length how to do it:

Links to bug report(s)

We have set up a bot that automatically picks up bug reports if the link(s) to the bug in question appear(s) in the body of the commit message. The bot then writes a message in the bug report and/or closes it. That way, you can quickly let other users know a patch or a fix has landed in the tree.

This feature helps Gentoo developers save time as they don't have to switch back and forth between Bugzilla, GitHub and their terminal to figure out which bug reports must be closed or not.

How does it work?

The bot can parse two types of header:


will automatically write a message in the bug report without closing it.


will automatically write a message in the bug report, change the status of the bug report to RESOLVED and the resolution to FIXED.

If the commit involves several bug reports, you can mention and stack the links. The bot will write a message in each bug report:


It also works with the Closes: header:


Feel free to add as much information as possible: upstream forums, mailing lists, discussions, links to changelogs, etc. The bot won't post messages all over the place though, but these useful information will appear in the ChangeLog file of the ebuild.

Ping maintainers

Once your PR is filed, if the maintainer has a GitHub account, ping him/her using @ followed by his/her user account. We've created GitHub groups which can be pinged at once: for instance @gentoo/gnome will ping the gnome team, @gentoo/java the Java team and so forth. Unfortunately, not all Gentoo projects have been mapped as GitHub groups yet. In any case, maintainers must know the existence of your PR. You can see a package's maintainers by either looking at ${PORTDIR}/${category}/${package-name}/metadata.xml files or using

user $equery meta ${category}/${package}

from the app-portage/gentoolkit package.

QA checks

gentoo-repo-qa-bot is engaging in a conversation with me in the PR. I don't understand.

Checks have failed for this pull request

We have set up an automated CI system which performs various QA checks when a PR is filed. These checks may result in two possible outcomes displayed next to your PR:

  • a green check-mark meaning everything's fine and your PR isn't offending the tree.
  • a red cross meaning something is up and your PR needs fixing.

Our QA bot is chatty when a red cross shows up. At this point, it might point out two types of error:

Issues persisted from underlying repository state:

This error means that unfortunately, you forked the tree whilst it was in a very unstable state (meaning broken). Indeed, every now and then developers break the tree and, tough luck, it turns out you forked the tree into your GitHub profile or synced it up at this very moment. But no big deal as there's nothing for you to do.

New issues:

This error is a bit more serious and means your PR isn't complying with our QA standards. Usually, one or more link(s) are displayed right below for you to visualise in a browser what it's all about. Go ahead, take a look and fix those errors. Push again and wait for the bot to go over your PR again (every 30 minutes) until a green check-mark appears.

See also