Gentoo GitHub

From Gentoo Wiki
Jump to: navigation, search

Hello fellow contributor!

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, make our lives (and yours!) easier and have your contribution quickly accepted.

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

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. If you're not familiar with git and pull requests, here are two must-read how-tos:

New packages

You want to add a new package to Gentoo? This way! To begin with, you must file a bug prior to filing a PR 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.

Use of repoman

We strongly encourage the use of the 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 repoman -dx full, so you should at least run this before committing. You can also use repoman to make commits using 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!

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 PR 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.

In the following example, assume that you originally submitted a pull request to bump the package app-misc/foo to version 0.2. At a first glance, a developer realized that the ebuild you submitted is missing a few runtime dependencies. So you've fixed them in another commit and pushed. Later on, you've added more fixes to the ebuild which resulted in yet another commit. Your git history will look similar to the following, although slightly different depending on which commit your master points to and which development branch you are working on:

Gentoo github squash figure 1.png

Because these three commits constitute a single logical change, which is the version bump, we need to squash them into a single commit. In git, we accomplish this by using interactive rebase. To initiate the rebase for the last 3 commits on your branch, issue the following git command:

user $git rebase -i HEAD~3

Git will pop up an editor with the following content (lines beginning with # are omitted in the output for brevity):

pick 402fee3 app-misc/foo: version bump to 0.2
pick f87716a app-misc/foo: fix runtime dependencies based on developer feedback
pick 9423dcf app-misc/foo: more fixes that should have been included in the original bump

This is a list of the last 3 commits with the most recent one listed first. We want to include the second and the third commits in the first commit. In other words, we want to pick the first commit, fixup the other two. Therefore, change the first word in every line to the following:

pick 402fee3 app-misc/foo: version bump to 0.2
f f87716a app-misc/foo: fix runtime dependencies based on developer feedback
f 9423dcf app-misc/foo: more fixes that should have been included in the original bump

where f is just a short-hand alias for fixup. Upon closing the editor, git will rebase the three commits into one. If you wish to be able to edit the commit message of the resulting commit, replace fixup with squash instead.

Rebasing permanently rewrites your commit history. Therefore, when you need to push the commit to GitHub, you need to add the --force flag to git:

user $git push --force
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.11 KiB | 0 bytes/s, done.
Total 5 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To git@github.com:gktrk/gentoo.git
 + 9423dcf...7d48b55 foo-bump -> foo-bump (forced update)

External links

Feel free to add as much information as possible: upstream forums, mailing lists, discussions, links to changelogs, etc. Your commit will appear in the ebuild ChangeLog file.

Bug report

If your commit solves a bug, mention the bug number using the #nnnnnn format in the summary line, e.g.:

dev-foo/bar: Fix frobnication, #123456

If there are multiple bugs involved (too many to keep a concise summary line), you can mention additional bugs using tags at the end of commit message:

Bug: https://bugs.gentoo.org/123456
Bug: https://bugs.gentoo.org/456789
Bug: https://example.tld/upstream-bugs/111111

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 file when a package is bumped or a new ebuild is introduced to the tree. DO NOT USE PASTEBIN! There are much better alternatives out there, https://bpaste.net/ for instance.

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 equery meta ${category}/${package} from the app-portage/gentoolkit package.

Happy GitHubing!

Q & A

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 half hour) until a green check-mark appears.

See also