qa-robot(1)

QA-ROBOT(1)

User Contributed Perl Documentation

QA-ROBOT(1)

NAME

qa-robot - simple notification system

SYNOPSIS

qa-robot [-h] [-a arch] [-b branch] [-d workdir] [-j] [-n] [-m mailto] [-s subj] cmd [args]

DESCRIPTION

qa-robot reports various state changes, in terms of new, old, and (possibly) updated entries. cmd must be a shell script which, whenever sourced or executed, dumps its current state to "stdout", one line per entry; the script may also provide its custom formatting routines.

OPTIONS

-a string: Set arch name. No defaults.
-b string: Set branch name. Default is "Sisyphus".
-d workdir: Use workdir working directory. Save cmd state under workdir. Default working directory is "$HOME/.qa-robot/$(basename cmd)/branch".
-j: Enable join mode; join records on the first field. Fields must be separated by tabs.
-n: Do not finally replace the old cmd state with the new one. Useful for test runs.
-m mailto: Suppress normal output. Send email notification to mailto address(es) instead. Messages larger than 32K are sent as gzipped attachments. Messages larger than 1024K produce a fatal error.
-s subj: Specify initial subject for email message.
-h: Display this help and exit.

FILES

Files in use under the working directory

dump.new, dump.old: Current and previous cmd state files.
comm.plus, comm.minus: Comparison between dump.new and dump.old. comm.plus has lines unique to the current state, while comm.minus has lines unique to the previous state.
join.new, join.old, join.updated: In join mode, comm.plus and comm.minus' lines are treated as records, whose fields are separated by tabs. The first field must be a primary key. comm.plus and comm.minus are then joined on the first field.
Thus join.new has records unique to comm.plus (i.e. lines in comm.plus unpairable with those in comm.minus), join.old has records unique to comm.minus, and join.updated contains pairable records joined on the first field.
lock: Semaphore file, to guard against simultaneous runs.
message: The report is saved to this file.
signature: When email message is sent, this file, should it exist, is appended to the message (except when sending gzipped attachments).

Other files

$PATH: Default cmd script location.
$HOME/.qa-robot/$(basename cmd): Default working directory.

FORMATTING

Variables

noun: A countable noun that describes the entries, in the singular number.
subj: The message subject.

Functions

fmt_start

Executed when formatting is started.

fmt_plus, fmt_minus

Main formatting routines, for displaying new and old entries; executed only when the entries have actually been found. Calling convention for these routines is as follows:

        fmt_$s $n $noun <comm.$s

where $n is the number of entries, $noun is the noun that describes the entries (in the proper number, according to $n), and "comm.$s" is the appropriate file, connected to "stdin", with $n entries in it.

fmt_new, fmt_old, fmt_updated

Alternative formatting routines for join mode (similar to fmt_plus and fmt_minus).

fmt_total

Formatting routine for the total number of entries.

        fmt_total $n $noun <dump.new

EXAMPLES

qa-robot comes with a few real-world components used by ALT QA Team to notify subscribers of ALT Linux mailing lists:

unmets: Reports new and resolved unmet dependencies. Creates aptbox to distance the host system setup.
bugs [URL]: Bugzilla watchdog. Reports new and resolved bugs (whether a bug has been resolved is subject to specific bugzilla conventions), along with the total number of pending (i.e. unresolved) bugs.
The URL specifies base Bugzilla URL. The default base URL is <https://bugzilla.altlinux.org>.
packages [DIR]: Reports new, old (removed), and updated rpm packages under DIR directory. Last changelog entry is listed for new and updated packages.
The default DIR is "$sisyphus/files/SRPMS", where $sisyphus is vendor-specific location.

BUGS

qa-robot is executed in "noglob" and "errexit" mode, so is the cmd sciprt.

After cmd script is sourced, the current working directory is set to workdir and may not be changed by formatting routines.

The locale is set to "LC_ALL=C".

AUTHOR

Written by Alexey Tourbin <at@altlinux.org>.

COPYING

This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

2023-11-23

perl v5.34.1