This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Gentoo GitHub
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 https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=ffbceb3c1d0887b5db7995fa850ed04a26aca212 for instance.
New means there is no older version in the tree yet.
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 fullso you should at least run this before committing. You can also use repoman to make commits using
user $repoman -dx commitWhen 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
Repoman can sign git commits by using app-crypt/gnupg, which then can be verified by github.com. 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 repoman
We need to enable the sign feature in portage and set the appropriate key ID:
/etc/portage/make.confFEATURES="... sign ..." PORTAGE_GPG_KEY="<GnuPG fingerprint>"
Upload the public key to GitHub
Last thing needed is to upload the public GnuPG key to github.com. 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: 128In 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:
${HOME}/.bashrcexport 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: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
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:
Bug: https://bugs.gentoo.org/123456
will automatically write a message in the bug report without closing it.
Closes: https://bugs.gentoo.org/123456
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:
Bug: https://bugs.gentoo.org/123456 Bug: https://bugs.gentoo.org/456789 Bug: https://bugs.gentoo.org/101010
It also works with the Closes: header:
Closes: https://bugs.gentoo.org/123456 Closes: https://bugs.gentoo.org/456789 Closes: https://bugs.gentoo.org/101010
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.
Build log
Due to the sheer amount of PRs that is coming our way on GitHub, and the limited number of developers looking after them, we cannot thoroughly test all PRs. Therefor, we kindly ask you to provide a link to a build log when a package is bumped or a new ebuild is introduced to the tree. Please attach the logs to the bug ticket.
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.
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
- Github Pull Requests —
- Gentoo git workflow
- Project:GitHub/Pull requests
- Submitting ebuilds - Gentoo's classical method of submitting ebuilds