GitHub Pull Requests

From Gentoo Wiki
(Redirected from Github Pullrequests)
Jump to: navigation, search
Workflow of a user contribution. The green arrows show the path of contribution. Grey arrows are optional, possible access directions.

Step 1 User configuration

Variant a: User configures a local repository

Clone the github mirror of the Gentoo repository under the remote name "upstream" into the path/to/save directory. (Replace path/to/save with the directory of choice.

user $git clone -o upstream path/to/save

Step into the new directory, fork the Gentoo repository on GitHub and then add it under the remote name "github" to your local repository.

Github fork.png
user $cd $_
user $git remote add github <UrlOfYourFork.git>

Variant b: Using the git repository as the primary portage tree

This setup is not fully functional since the plain developer repository as obtained from github lacks the metadata generated for the official tree.
root #mkdir /etc/portage/repos.conf/

Add the following to the file:

FILE /etc/portage/repos.conf/gentoo.conf
    location = /var/db/repos/gentoo
    sync-type = git
    sync-uri =
    auto-sync = yes
    sync-user = portage:portage

Add the following, changing <dev_user_name>.

FILE /etc/portage/repo.postsync.d/99-user-dev-perms
find /var/db/repos/gentoo/ -type d -exec setfacl -m u:$USER_NAME:rwx {} \;
find /var/db/repos/gentoo/ -type f -exec setfacl -m u:$USER_NAME:rw {} \;
find /var/db/repos/gentoo/.git -type d -exec setfacl -m u:$USER_NAME:rwx {} \;
find /var/db/repos/gentoo/.git -type f -exec setfacl -m u:$USER_NAME:rw {} \;
root #chmod +x /etc/portage/repo.postsync.d/99-user-dev-perms

Then sync the repository.

root #emerge --sync

Fork the Gentoo repository on GitHub

Github fork.png

And then add it under the remote name "github" to your local repository.

user $cd <overlay_path>
user $git remote add github <YOURURLHERE>

Step 2: set up the repo's config

user $cd <overlay_path>
user $git config --local "Your Full Name"
user $git config --local "example@domain.tld"
user $git config --local pull.ff only
user $git config --local pull.rebase merges
user $git config --local push.default simple

Step 3: GPG Configuration

Add the following to dirmgr.conf and gpg.conf respectively:

FILE ~/.gnupg/dirmngr.confTLS Communication to the Keyserver
hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem
FILE ~/.gnupg/gpg.confGeneral GPG Setup
keyserver hkps://
keyserver-options no-honor-keyserver-url
cert-digest-algo SHA512
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed

Now to generate the key:

user $gpg --full-generate-key
   Select the algorithm
   Set the key size
   Specify how long the key should be valid (No more then 5 years)
   Confirm the information is correct
   Set your name
   set your email
   Set your passphrase, and confirm it.

It might take some time if you've chosen a high bit length key.

Retrieve your GPG public keyID via the following command:

user $gpg --list-public-keys --keyid-format 0xlong example@domain.tld

The key id is the portion after the <algorithm>/ on the line beginning with pub as shown in bold below. If you have more than one key with the specified UID you will need to select the correct key yourself from the list of returned keys.

    pub   rsa4096/0x000000000000000

Upload your key to the keyserver.

user $gpg --keyserver --send-key example@domain.tld

Note that under some circumstances it may be necessary to provide a keyID to the '--send-key' flag. For example

user $gpg --keyserver --send-key 0x000000000000000

Finally, configure git to use the target key for code signing and properly sign-off all your commits:

user $git config --local user.signingkey 0x000000000000000
user $git config --local commit.gpgsign 1
user $git config --local push.gpgsign 0

Step 4: User updates the local repository

user $git checkout master
user $git pull upstream master

Step 5: User changes a package

Circular workflow step1.png

Say you are making changes to package app-foo/bar. Create a local branch with your changes:

user $git checkout -b app-foo/bar master

Make your changes and make sure to run repoman to check for basic errors:

user $repoman -dx full

Then commit your changes (if you're closing some bugs on Bugzilla, you can mention them here as suggested by GLEP66). Note that if you intent to open a pull request and get your contribution in to the main tree, you need to properly sign-off all your commits as configured in step 3. Please see GLEP-76 for more information.

user $repoman ci

Step 5: User makes a pull request

Circular workflow step2.png

Now that you've made your changes and updated your local branch, it's time to send it off to GitHub and make a PR (Pull Request) to the Gentoo Developers.

Start by pushing the branch with your changes to your GitHub repository:

user $git push github app-foo/bar

Then create a pull request from your GitHub repository's local branch to the Gentoo repository's master branch. When your changes have been merged, you may delete your local repository's branch with:

user $git checkout master
user $git branch -d app-foo/bar

Step 6 Developer fetches the PR and reviews

Variant a: manually

Circular workflow step3.png
dev $curl -s -L "" | git am -S
dev $repoman full -x
dev $ # tests

Variant b: By means of the PRam tool

The PRam tool app-portage/pram helps developers to merge pull requests. To merge GitHub PR #12345, enter your local gentoo.git checkout and run

user $pram 12345

see also

Step 7: Developer merges to the tree

Circular workflow step4.png
dev $git push --signed origin master

See also

External resources