Github Pull Requests

From Gentoo Wiki
Jump to: navigation, search

GitHub pull requests for Users and Proxied Maintainers (please shorten this)

Workflow of a user contribution. The green arrows show the path of contribution. Grey arrows are optional, possible access directions.

The most efficient way of submitting your contributions is through pull requests on our GitHub repository. At the moment, it gives the best response time, the widest audience for reviews and some nice scripting (including CI) to help.

Once you push your new branch, visit the GitHub page of your fork. GitHub will show you a banner suggesting creating a pull request. Using it, you can avoid the necessity of specifying the fork and branch manually.

Once the pull request is created, our tooling will automatically CC the relevant people (maintainers and/or proxy-maint team) and perform basic QA checks via pkgcheck. If any issues are reported, please fix them or explicitly ask for help. Our reviewers may skip pull requests which are marked as not passing CI.

Afterwards, follow the suggestions given by reviewers and push updates until the pull request is fully approved. If you do not receive a reply within a reasonable time, please make sure to ping us on the pull request. When it's ready and approved, we'll merge it.

Please keep the same commit structure as you would use when committing straight to Gentoo as a developer, and follow the best git practices (atomic changes, proper commit messages). For smaller changes, we can squash and reword the commits for you. However, if you are going to actively maintain multiple packages or submit larger changes, we will require you to squash, split and word your commits appropriately. Please see the git documentation on rewriting history. Once you've got updated commit set, use git push --force to overwrite your previous commits on the pull request branch.

Step 0 variant a: User configures the local repository

Clone the github mirror of the Gentoo repository under the remote name "upstream".

user $git clone -o upstream
Fork the Gentoo repository on GitHub and then add it under the remote name "github" to your local repository.
Github fork.png
user $git remote add github <UrlOfYourFork.git>

Step 0 variant b: using git as the main portage tree

root #mkdir /etc/portage/repos.conf/
root #vim /etc/portage/repos.conf/gentoo.conf

Add the folowing to the file:

   location = /usr/portage
   sync-type = git
   sync-uri =
   auto-sync = yes
   sync-user = portage:portage
root #vim /etc/portage/repo.postsync.d/99-user-dev-perms

Add the following, changing <dev_user_name>.

   find /usr/portage/ -type d -exec setfacl -m u:$USER_NAME:rwx {} \;
   find /usr/portage/ -type f -exec setfacl -m u:$USER_NAME:rw {} \;
   find /usr/portage/.git -type d -exec setfacl -m u:$USER_NAME:rwx {} \;
   find /usr/portage/.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 tree.

root #emerge --sync
Fork the Gentoo repository on GitHub and then add it under the remote name "github" to your local repository.
Github fork.png

Add your remote fork you created under the remote name "github" to your local repository.

Step 1: set up the repo's config

user $cd <overlay_path>
user $git remote add github <YOURURLHERE>
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 preserve
user $git config --local push.default simple

Step 2: GPG Configuration

user $vim ~/.gnupg/gpg.conf

Add the following:

   keyserver hkps://
   keyserver-options ca-cert-file=/usr/share/gnupg/sks-keyservers.netCA.pem
   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.

Upload your key to the keyserver.

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

To get your GPG key run this command. It should be the top line (starting with pub). If you have more than one key with the UID you will need to select the correct key yourself (from the list of returned keys).

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

You want the keyID from the line that starts with 'pub' and what is after the algorithm and the / eg:

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

Step 3: User updates the local repository

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):

user $repoman ci

Step 4: 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 branch -d app-foo/bar

Step 5: Developer fetches the PR and reviews

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

Step 6: Developer merges to the tree

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