Project:GURU/Information for Contributors

Prior setup

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

• Please read the GURU project rules.
  • Agreeing to the rules is required before submitting any contribution.

• Start submitting contributions either through Codeberg pull requests, or submit patches to [email protected] mailing list.
  • Please use the AGit workflow, preferably via dev-vcs/gagit or a similar tool that respects pull request templates.

• After having a few contributions merged, please file an access request, including:
  • Your desired name (per the copyright policy)
  • SSH key
  • (For bonus points, you can also include the fingerprint of your OpenPGP key but this is currently not necessary.)
  • Whether you agree to the GURU project regulations.
  • Links to your merged contribution.

• A trusted contributor will either approve your request immediately or give you some additional work to do.

Repository/git setup

To clone the repository:

user $git clone -b dev [email protected]:repo/proj/guru.git

This automatically selects the dev branch. Please commit to this branch, and do not ever commit to master directly.

In order to submit pull requests, adding a Codeberg remote is recommended:

user $git remote add codeberg [email protected]:gentoo/guru

Using the following settings is recommended:

user $git config --local pull.ff only

user $git config --local pull.rebase merges

user $git config --local commit.gpgsign 1

user $git config --local push.gpgsign 1

user $git config --local push.default upstream

This, in order:

1. Blocks git pull from creating merge commits when you have local commits.
2. Enables automatic rebasing on git pull (eq: git pull --rebase).
3. Enables OpenPGP-signing commits (eq: git commit -S).
4. Enables OpenPGP-signing push certificates (eq: git push --signed).
5. Configures git push to push to the upstream of the current branch by default. This is useful for updating pull requests made via AGit workflow.

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:

user $git config --local user.name "Your Full Name"

user $git config --local user.email "[email protected]"

user $git config --local user.signingkey KEY-FINGERPRINT

This, in order:

1. Sets the author and committer name (please use your real name).
2. Sets the author and committer e-mail address.
3. Sets the identifier of OpenPGP key to use for signatures.

Pkgcruft git hook (optional)

Tip
dev-util/pkgcruft will run these same QA checks via pkgcruft scan . or variations on that command

To ensure that commits with QA issues are not accidentally pushed to the repository (and to reduce the amount of trusted contributor and developer time when merging commits into master), pkgcruft (from the Pkgcraft suite) can be run as a git hook to reject commits with QA issues before they are sent upstream.

Tip
This does not (currently) replace pkgcheck scan --commits, however it's fast and great for catching missed pkgchecks or issues caused by quick fixups.

To install the git hook, first install dev-vcs/pkgcruft-git:

root #echo 'dev-vcs/pkgcruft-git **' > /etc/portage/package.accept_keywords

root #emerge --ask dev-vcs/pkgcruft-git

To enable pkgcruft-git in a given repository, either symlink the binary to the pre-push hook, or configure it for a particular remote (or alongside other hooks):

user $ln -s /usr/bin/pkgcruft-git-pre-push /var/db/repos/guru/.git/hooks/pre-push

or

user $echo 'pkgcruft-git-pre-push origin [email protected]:repo/proj/guru.git' > /var/db/repos/guru/.git/hooks/pre-push

user $chmod +x .git/hooks/pre-push

Tip
Match the remote URI to the output of git remote -v

Then configure pkgcruft to know where the GURU repository is:

FILE /etc/pkgcraft/repos/gentoo

location = "/var/db/repos/gentoo"
format = "ebuild"

FILE /etc/pkgcraft/repos/guru

location = "/var/db/repos/guru"
format = "ebuild"

pkgcruft will run a QA check every time git push is invoked and will reject the push if QA issues are detected.

Contributing

Via pull requests

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, create a new branch for your changes. Use a unique name that indicates what you're doing:

user $git checkout -b add-nifty-package

Please make sure you've staged (via git add) all your changes correctly. Use the following command to confirm this:

user $git status

Important
You should use dev-util/pkgcheck to check for QA issues.

It is recommended to use dev-util/pkgdev for committing. To commit use:

user $pkgdev commit --signoff

Alternatively (or whenever direct use of pkgdev is insufficient), please use:

user $pkgcheck scan --net

user $git commit -sS

After committing, it is recommended to look through your changes via:

user $git log -p

Then create a pull request using dev-vcs/gagit:

user $gagit

Either edit the pull request description in the provided editor, or in a browser once it's filed. Double check that everything is good, and mark it as "ready for review".

Directly to the repository

Once you have push access to GURU, you can push straight into the repository. In that case, you don't need to create a new branch, and you can work straight on dev.

Push your changes via:

user $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.

Following bugs

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 [email protected] 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.

See Project:GURU/Information_for_Trusted_Contributors.

Inactivity

Contributors who do not contribute to the repository for a period of more then 2 years may have their access revoked. An e-mail, as well as a comment on the original access request, will be sent to inactive contributors before their access is revoked. Contributors whose access has been revoked may regain access at some later date by requesting this on their original access request.