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.
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:
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
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).
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)
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).
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
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:
Or alternatively if using app-portage/iwdevtools:
Install the dependencies of the package:
emerge -av1o --with-test-deps app-misc/scrub
Copy the old ebuild as a basis for new changes and regenerate the Manifest:
cp scrub-2.6.0.ebuild scrub-2.6.1.ebuild
Go read the upstream release notes! Then compare the build system changes using pkgdiff -b from app-portage/mgorny-dev-scripts.
pkgdiff -b scrub-2.6.0.ebuild scrub-2.6.1.ebuild
Adapt the ebuild as needed:
Optionally run pkgcheck scan to check for QA issues during the work/change process:
Test it out (repeat as necessary):
ebuild scrub-2.6.1.ebuild clean test install merge
Try running the tool too (ideally use it):
scrub version 2.6.1
Commit the changes once ready (note that the command from the commit command shows pkgcheck scan results):
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
It can be roughly summarized as:
- Make changes
- pkgcheck scan --commits
- Make changes based on pkgcheck output
- pkgcheck scan --commits
- Once done, git rebase -i --autosquash
- Gentoo git workflow — outlines some rules and best-practices regarding the typical workflow for ebuild developers using git.
- Pkgcheck — a pkgcore-based QA utility for ebuild repos.
- Pkgdev — a collection of tools for Gentoo development.