Standard git workflow

Attempt at describing a modern git workflow with pkgcheck and pkgdev.

This tries to be an alternative to the Gentoo git workflow page which acts as more of a reference than a guide or tutorial.

Tools

The previous tooling, repoman, handled both QA scanning as well as acting as a commit helper.

The new workflow is split into two major components:

scanning for QA issues (pkgcheck)
committing the changes (pkgdev, or the far more spartan pkgcommit if desired)

First, install these essential tools:

root #emerge --ask dev-util/pkgcheck dev-util/pkgdev

Optionally, install these bits:

app-portage/mgorny-dev-scripts for additional helpers like pkgdiff to diff (build system) changes between versions. Their use is optional but it's worth reading over the list available.
app-portage/iwdevtools for file diff (compare old/new, check if e.g. files now missing), rcd helper to navigate packages, detecting missing dependencies via ELF NEEDED, etc

root #emerge --ask app-portage/mgorny-dev-scripts app-portage/iwdevtools

Checking for issues

pkgcheck is a QA scanning tool equivalent to the "check" part of repoman. Its main use is pkgcheck scan (equivalent to repoman full -dx).

See pkgcheck#Examples.

Committing changes

pkgdev

pkgdev is a commit helper, equivalent to the "commit" part of repoman.

Its main uses are:

pkgdev commit (equivalent to repoman commit), and
pkgdev manifest (equivalent to repoman manifest)

See pkgdev#Examples.

pkgcommit

pkgcommit is a helper tool from app-portage/mgorny-dev-scripts. It is not part of the pkgcore suite. It just generates the commit summary based on the current directory (no "smart generation" based on the actual changes like pkgdev).

Examples

The overall method is always the same:

Enter a repository
Navigate to a package (using app-misc/scrub as an example)
Make some changes
Run pkgdev commit (recommended) or alternatively pkgcommit

Bumping app-misc/scrub

Tip
Using app-portage/iwdevtools, a shortcut tool rcd can be used to quickly jump to a package.

This example uses pkgdev. When calling pkgdev commit, it calls pkgcheck scan automatically.

First, enter the repository the old fashioned way:

user $cd ~/git/gentoo/app-misc/scrub

Or alternatively if using app-portage/iwdevtools:

user $rcd scrub

Install the dependencies of the package:

root #emerge -av1o --with-test-deps app-misc/scrub

Copy the old ebuild as a basis for new changes and regenerate the Manifest:

user $

cp scrub-2.6.0.ebuild scrub-2.6.1.ebuild

user $pkgdev manifest

Go read the upstream release notes! Then compare the build system changes using pkgdiff -b from app-portage/mgorny-dev-scripts.

user $pkgdiff -b scrub-2.6.0.ebuild scrub-2.6.1.ebuild

Adapt the ebuild as needed:

user $$EDITOR scrub-2.6.1.ebuild

Optionally run pkgcheck scan to check for QA issues during the work/change process:

user $pkgcheck scan

Test it out (repeat as necessary):

user $ebuild scrub-2.6.1.ebuild clean test install merge

Try running the tool too (ideally use it):

user $scrub --version

scrub version 2.6.1

Commit the changes once ready (note that the command from the commit command shows pkgcheck scan results):

user $

git add scrub-2.6.1.ebuild && pkgdev commit

app-misc/scrub
  DeprecatedEapi: version 2.6.0: uses deprecated EAPI 6
  RedundantVersion: version 2.6.0: slot(0) keywords are overshadowed by version: 2.6.1
[master 65b81235dc06d] app-misc/scrub: add 2.6.1
 2 files changed, 17 insertions(+)
 create mode 100644 app-misc/scrub/scrub-2.6.1.ebuild

Bumping app-misc/scrub without pkgdev

mgorny describes on his blog an alternative workflow (from before pkgdev was created) based on pkgcommit and pkgcheck scan --commits.

It can be roughly summarized as:

Make changes
pkgcommit
pkgcheck scan --commits
Make changes based on pkgcheck output
git-fixup
pkgcheck scan --commits
...
Once done, git rebase -i --autosquash

External resources

https://blogs.gentoo.org/mgorny/2019/12/12/a-better-ebuild-workflow-with-pure-git-and-pkgcheck/