Usage

Commands

NATTkA exposes its functions as sub-commands of the nattka executable. The basic usage is:

nattka [<global options>...] <command> [<command arguments>...]

The following commands are supported:

apply

Applies keywords from specified bugs to the working tree.

commit

Commits previously applied keyword changes to git (does not push).

sanity-check

Perform sanity checks of specified bugs — fetch keywords, apply them to the local checkout, run pkgcheck and update the bugs if requested.

Global options

Global options are common to all commands. They must be specified before the command.

Logging control

Normally NATTkA prints verbose progress messages to the console.

If this is undesirable, -q (--quiet) option can be used to silence the output. Only critical failures preventing the program from starting and Python tracebacks on unexpected exceptions will be printed.

Alternatively, --log-file can be used to direct verbose logs into the specified file. If the specified file exists already, logs will be appended to it. Critical failures and Python tracebacks will still be printed to the console.

Bugzilla configuration

It is strongly recommended to generate Bugzilla API key and use it for Bugzilla communications. While it is possible to perform read-only actions anonymously, the returned data will not contain full e-mail addresses and will therefore be prone to mistakes.

The API key can be passed as --api-key option, or stored in ~/.bugz_token file. The former option overrides the latter file, if both are present.

NATTkA uses Gentoo Bugzilla by default. Another Bugzilla instance can be used by specifying --api-endpoint. It should contain full URL to the REST API endpoint, i.e. with /rest suffix.

Repository configuration

NATTkA assumes it is run within the ebuild repository by default. If this is not the case, the path to the repository can be specified using --repo option.

Normally, NATTkA uses default system configs for the package manager. --portage-conf option can be used to override this configuration directory and use another Portage-style configuration directory. This directory needs to contain at least make.profile symlink.

apply command

Basic usage

The apply command is used to apply keywords from a keywording or stabilization bug to the local checkout, and print the list for arch tester’s use.

NATTkA works for the system arch (as defined by the pkgcore/Portage config) by default. To work for another arch, pass it via -a (--arch) option. The option can be repeated and wildcards can be used to specify multiple targets, in particular * enables all known arches.

If a bug is marked ALLARCHES, the apply command automatically applies other keywords suitable for stabilization on all arches. If this is not desirable, --ignore-allarches can be used to disable it.

If you do not wish for NATTkA to apply keywords locally, and just print the list for you, pass -n (--no-update).

Specific bug numbers can be specified as positional arguments to the command, e.g.:

nattka apply 123456 123460

Alternatively, if no numbers are specified NATTkA finds all open keywording and stabilization bugs.

Filtering bugs

In both cases, additional options can be used to further filter the results. In general, separate conditions are combined using AND operator (i.e. only bugs matching all of them are returned), while different values for the same group of conditions are OR-ed together (i.e. all bugs having one of the values are processed).

--keywordreq limits processing to keywording requests, while --stablereq limits it to stabilization requests. Additionally, --security option can be used to limit results to security bugs.

Normally, NATTkA applies keywords only when the bug in question passed sanity-check. To disable this filter and process any bugs, pass --ignore-sanity-check.

NATTkA fetches dependencies of all bugs automatically. If this is undesirable, it can be disabled using --no-fetch-dependencies.

Any bug having unresolved dependencies is skipped. To ignore unresolved dependencies, use --ignore-dependencies. The recommended approach is to process and commit the dependencies first, and rerun the apply command once the blocking bug is marked fixed.

Note that you can set nattka:skip personal tag on the bug in order to omit it from search results. This will work only if NATTkA is using an API key (generated by the same user). The bugs can still be acted on by passing bug number explicitly.

Output

The apply command output is suitable for copying straight into the package.accept_keywords file. Additional information such as bug numbers, issues and target keywords for keyword requests are output as comments.

Example output:

# bug 701300 (KEYWORDREQ)
=app-admin/mongo-tools-4.2.2 **  # -> ~arm64
=dev-python/cheetah3-3.2.3 **  # -> ~arm64
=dev-db/mongodb-4.2.2 **  # -> ~arm64

# bug 700918: sanity check failed

# bug 700806 (STABLEREQ)
=net-mail/mailutils-3.8 ~arm64

# bug 699838: unresolved dependency on 706146, 706442

commit command

The commit command is used to commit keyword changes to the git repository. It should be used after apply. It takes care of using the correct package list and making reasonably good commit messages.

At the moment, the commit command does not autodetect which keywords were changed. Instead, you need to pass the same --arch options as to apply. You also need to pass --ignore-allarches if it was passed to apply.

Specific bug numbers must be specified as positional arguments to the command, e.g.:

nattka commit -a arm64 123456 123460

resolve command

The resolve command is used to update bugs after pushing. It takes care of unCC-ing arch teams, leaving a comment and closing the bugs if appropriate.

When using resolve, you need to pass the same --arch options as to apply. This is necessary in order to determine which arch(es) are done. You also need to pass --ignore-allarches if it was passed to apply.

Specific bug numbers must be specified as positional arguments to the command, e.g.:

nattka resolve -a arm64 123456 123460

Bugs are closed if no known arch teams are left in CC and they are not security bugs. The --no-resolve option can be used to inhibit closing bugs altogether.

The -p (--pretend) option can be used to display the actions that would be taken without performing them on the Bugzilla instance.

sanity-check command

Basic usage

The sanity-check command is used to perform sanity checks of open keywording and stabilization bugs.

The normal way of using it is to omit positional arguments, causing it to process all open keywording and stabilization bugs:

nattka sanity-check

Alternatively, specific bug numbers can be passed in order to limit the operation to them:

nattka sanity-check 123456 123460

Filtering bugs

In both cases, additional options can be used to further filter the results. In general, separate conditions are combined using AND operator (i.e. only bugs matching all of them are returned), while different values for the same group of conditions are OR-ed together (i.e. all bugs having one of the values are processed).

--keywordreq limits processing to keywording requests, while --stablereq limits it to stabilization requests. Additionally, --security option can be used to limit results to security bugs.

NATTkA fetches dependencies of all bugs automatically. If this is undesirable, it can be disabled using --no-fetch-dependencies. Note that bugs with unsatisfied dependencies will be skipped to avoid reporting false positives.

Limiting processing

Normally, NATTkA processes all bugs specified on the command line or found on Bugzilla. This can result in very long run times, and when run repeatedly it can cause delays in processing new bugs.

The --bug-limit option takes a number of bugs to be checked. It can be used to cause the program to terminate after processing this many bugs, opening the possibility of starting it again to tackle newly filed bugs. Only bugs actually processed by pkgcheck are counted towards the limit (i.e. not bug skipped).

The --time-limit option takes maximum run time in seconds. Once the program runs for specified time, it gracefully exits after processing the current bug.

Caching

By default, NATTkA retests all specified bugs. This is not strictly a problem since bugs are updated only if the new status differs from the last status reported to the bug. However, with large number of bugs open it can cause every program run to last very long.

Caching can be used to resolve that problem. It can be enabled via passing -c (--cache-file) option along with a path to a JSON cache file (it will be created it if it does not exist).

When cache is enabled, NATTkA stores check results along with bug information (package lists, sanity-check flag) in it. When it is run again, it verifies whether the cache entry is up-to-date (i.e. the bug has not changed and the entry has not expired) and skips rechecking packages where it is unnecessary.

Combined with --bug-limit or --time-limit, cache makes it possible to restart NATTkA often while permitting it to combine quick processing of newly filed bugs with periodically rechecking historical bugs.

--cache-max-age option can be used to specify how often bugs should be rechecked, in seconds. The default value amounts to 12 hours.

Bug updates

For safety reasons, bug processing is normally run in ‘pretend mode’. Bugs are checked for correctness but the results are only output to console (logs). If you are ready to run it in production and enable posting to bugs, append -u (--update-bugs).

Please note that this requires an API key to be present. It is strongly recommended that this API key belongs to a separate account used only by NATTkA.

make-package-list command

This is an experimental command to help creating package lists for keywording requests. To get list for rekeywording (i.e. restoring lost keywords) on a package, run it inside the repository as:

nattka make-package-list dev-python/virtualenv

If you’d like to keyword for specific arches, pass them using --arch option (note: unlike with other commands, the value of this option is used verbatim on the package list):

nattka make-package-list -a 'ppc ppc64' dev-python/elementpath

Please note that this function is still experimental. It may fail with non-trivial dependencies, and it may generate excessive dependency lists when dealing with || syntax (read: it will attempt to keyword everything, even if it can’t satisfy the dependency).