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
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
See Also
- 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.