NATTkA -- A New Arch Tester Toolkit

Author:	Michał Górny
License:	GPL-2.0-or-later
Homepage:	https://github.com/mgorny/nattka/
Documentation:	https://dev.gentoo.org/~mgorny/doc/nattka/

NATTkA is a combined replacement for Gentoo keywordreq/stablereq sanity checking tool stable-bot, and its client getatoms.py. It is meant to make preparing and processing keywording bugs more consistent and easier. NATTkA specifically focuses on activity relevant to Bugzilla — verifying bugs, getting package lists, committing changes (based on bugs ☺) and closing bugs.

Features

The primary features of NATTkA are:

• Fast sanity checking of requests using pkgcheck backend, even if arches are not CC-ed yet (if keywords can be determined from package list).
• Support for generic package dependency syntax in package list field for keywording requests, removing the requirement to explicitly specify one package version and keep it updated.
• apply command that replaces getatoms.py, with support for applying keywords in place and dependency sort of output.
• commit command that takes care of committing keyworded packages with automatically generated commit messages.
• resolve command that takes care of unCC-ing arches from bugs, and closing them if appropriate.
• Automatic CC-ing of the correct arch teams via CC-ARCHES keyword.
• Support for ALLARCHES stabilizations.

Filing keywording/stabilization bugs

NATTkA uses the same Bugzilla features as stable-bot. It processes bugs filed in keywording/stabilization-related components, with package list field filled in. The results of sanity check are reported via flag and comment on the bug.

Package list names one package per line (using CPV or package dependency specification form), optionally followed by one or more keywords.

For stabilization requests, exact package versions must be specified. For keywording requests, generic specifications can be used instead. If they match multiple versions, the program will determine the newest suitable version.

Tilde before keywords is optional and does not influence the behavior — stable or testing keywords are used depending on component used. If keywords are listed for all packages, the bug can be checked even before arch teams are CC-ed.

In place of explicit (or implicit) keywords, additional tokens can be used to save typing:

• ^ that copies keywords from the previous package on the list.
• * that aligns keywords to other versions of the package.

Once arch teams are CC-ed, effective keywords are determined as the intersection of specified keywords and CC-ed arches. Packages listed without keywords are assumed to be requested on all CC-ed arches.

Alternatively to CC-ing arch teams, the CC-ARCHES keyword can be added to a bug. In that case, NATTkA will automatically determine arch teams from the package list field and CC them, as long as the bug passes sanity check.

NATTkA scans package metadata.xml files for stabilize-allarches element. If all packages on the package list have one, it automatically adds ALLARCHES keyword. Otherwise, it ensures that this keyword is not present.

Example package list follows:

dev-bar/libfrobnicate-9.0
dev-foo/frobnicate-1.2.3 amd64 x86
dev-libs/libdependency-7.7.7 ^

Detailed information on Bugzilla use can be found in the bug processing section of the documentation.

Basic usage help

NATTkA uses Python's argument parser with subcommand support. To get help on global options and available commands, type:

nattka --help

To get help on command-specific arguments, type:

nattka <subcommand> --help

Please note that global options must be passed before the command, and command-specific options after it.

Detailed help on command-line options can be found in the usage section of the documentation.

Using NATTkA for arch testing

The following workflow assumes that you are working on gentoo.git repository clone, and running NATTkA inside the checkout. You should generate API key and put it in ~/.bugz_token file (as used by old versions of pybugz) or pass via --api-key global option.

First, use the apply command to get some pending bugs and apply their keywords to your local checkout.

To process a specific bug, pass its number:

nattka apply 123456 123458

To find and process all open bugs, run the command without any arguments:

nattka apply

Search results can further be narrowed:

nattka apply --keywordreq
nattka apply --stablereq
nattka apply --security

To run for another arch than host's:

nattka apply -a arm64 ...
nattka apply -a hppa -a sparc ...
nattka apply -a '*' ...

To disable modifying keywords on packages and just output a list suitable for copying into package.accept_keywords:

nattka apply -n ...

To disable skipping bugs that did not pass sanity check or have unresolved dependencies:

nattka apply --ignore-sanity-check ...
nattka apply --ignore-dependencies ...

To disable performing ALLARCHES stabilizations:

nattka apply --ignore-allarches ...

After successfully testing the packages, use commit command to commit the changes:

nattka commit [-a ...] [--ignore-allarches] 123456

Then check and push them:

pkgcheck scan --commits
git push --signed

Finally, update the bugs:

nattka resolve [-a ...] [--ignore-allarches] 123456

A little more details can be found in the quick start section of the documentation.