Project:GURU/Information for Contributors
- In order to commit to GURU, you need to have a SSH key (used to access the server) and OpenPGP key (used to sign commits and push certificates). If you don't have OpenPGP key yet, following GLEP 63 rules as much as possible is recommended. Generating GLEP-63-based OpenPGP keys is a decent guide to creating the key.
- Please also make sure to read Certificate of Origin, as you will be required to confirm the acceptance of its terms in every commit. Its purpose is to confirm that your commits do not violate copyright.
- Once you're ready, please file an access request, including:
- your real name
- preferred e-mail address (you will receive bug mail and other comms on this address)
- SSH key
- (For bonus points, you can also include the fingerprint of your OpenPGP key but this is currently not necessary.)
- Please read the project regulations. Agreeing to the regulations is a condition of access. If you agree to these, please state so in the bug you file.
To clone the repository:
git clone -b dev email@example.com:repo/proj/guru.git
This automatically selects the dev branch. Please commit to this branch, and do not ever commit to master directly.
Using the following settings is recommended:
git config --local pull.ff only
git config --local pull.rebase merges
git config --local commit.gpgsign 1
git config --local push.gpgsign 1
This, in order:
- Blocks git pull from creating merge commits when you have local commits.
- Enables automatic rebasing on git pull (eq: git pull --rebase).
- Enables OpenPGP-signing commits (eq: git commit -S).
- Enables OpenPGP-signing push certificates (eq: git push --signed).
Furthermore, you may need to include one of the following if you haven't set them globally already, and the defaults do not work for you:
git config --local user.name "Your Full Name"
git config --local user.email "firstname.lastname@example.org"
git config --local user.signingkey KEY-FINGERPRINT
This, in order:
- Sets the author and committer name (please use your real name).
- Sets the author and committer e-mail address.
- Sets the identifier of OpenPGP key to use for signatures.
You will also need to include the matching settings in /etc/portage/make.conf:
PORTAGE_GPG_KEY='KEY-FINGERPRINT' SIGNED_OFF_BY='Your Real Name <email@example.com>'
This, in order:
- Sets OpenPGP key to be used for committing.
- Enables Certificate of Origin signoff, and sets your name and e-mail address for it.
If you haven't used git before, looking through a good guide first is recommended. We recommend the Pro Git Book. GLEP 66 provides recommended Gentoo-specific policies. Long story short, we recommend doing one commit for each change, and starting commit messages with category/package-name: ...
Before committing, please make sure you've staged (via git add) all your changes correctly. Use the following command to confirm this:
You should use dev-util/pkgcheck to check for QA issues.
It is recommended to use dev-util/pkgdev for committing. To commit use:
Alternatively (or whenever direct use of pkgdev is insufficient), please use:
pkgcheck scan --net
git commit -sS
After committing, it is recommended to look through your changes via:
git log -p
Then push them via:
git pull --rebase && pkgdev push -A
If errors occur, please investigate whether they are related to your changes. If not, please consider helping to fix the issues, but you can push if you're new and unsure how to resolve them.
Bugs regarding packages in GURU are assigned/CC-ed to the opt-in guru-bugs alias. If you wish to follow bug mail, please visit Email preferences on Gentoo Bugzilla, and add firstname.lastname@example.org to your watch list.
Becoming a Trusted Contributor
If you have done some good work for GURU already, and feel like taking more responsibilities, you can become a Trusted Contributor and gain the privilege of reviewing commits and merging them to master. In order to do so, please file a bug requesting ascension. The developers will verify your contributions and grant you Trusted Contributor status.