fedora-review - Man Page

Customized review template for Fedora packages

Synopsis

fedora-review [options] -b <bug> fedora-review [options] [--prebuilt] -n <package name> fedora-review [options] [--prebuilt] -rn <srpm path> fedora-review [options] -u <url>

Makes reviews of rpm packages for Fedora easier by providing a customized review template, automating some trivial tasks. The tool runs a number of checks to test whether a package complies to the Fedora Packaging Guidelines before creating the template. Through a bash API the checks can be extended. We have at the moment checks for C/C++, R, Java and Perl packages.

Usage

Basic usage:

$ fedora-review -b <bug number>
$ fedora-review -u <url>

Will download the SPEC & SRPM files from the Bugzilla report, build them in mock, run a number of tests and generate a template.

Not all bugzillas support the -b option. The -u option is available for these. See --url usage notes below.

$ fedora-review -n <package name>

This alternative usage expects <package name>.spec and source rpm in current directory. By adding the -p switch, fedora-review uses already built rpms in current directory instead of building using mock.

$ fedora-review --rpm-spec -n <srpm path>

This form accepts a single path to a source rpm. It uses the specfile bundled in the srpm package.

You will need to have mock installed and be member of the mock group for the build to work. Run as root:

# usermod -a -G mock [your user name]

After this, you will need to logout and login again (or use newgrp(1)) - the changes in user's group list is not read until a new login.

MODE OPTIONS - one is required

-b, --bug <bug nr>: Run against Fedora bugzilla at bugzilla.redhat.com, using the bugzilla bug number
--copr-build <build_descriptor>: Run against COPR build identified by its ID, frontend build uri, or backend build chroot uri. Checks for overall build success and looks up rawhide build results of the client machine arch. Implies --prebuilt.
-n, --name <name>: Runs the checks against the named spec and source rpm located in the current working directory. The files are expected to have the names <name>.spec and <name>*.src.rpm. When used together with --rpm-spec/-r, name can also be a complete path to a source rpm.
-u url, --url <url>: Fetch data from given url, typically another bugzilla instance such as rpmfusion. Before using this, first try the more convenient --bug <bug nr> --other-bz <url>. The option tries to retrieve the URL:s by scanning the page. See URL Limitations for how the url must look to be found.
-d, --display-checks: List all available checks, usable as arguments to --exclude and --single
-f, --display-flags: List all available flags, usable as arguments to --define or -D.
-g, --display-plugins: List all plugins which can be enabled/disabled using --plugins.
-V, --version: Show version info

General Options

-B, --no-colors

Disable use of ansi colors in console output.

-c, --cache

Do not redownload the files from bugzilla or upstream, use the local ones from previous run instead.

-D, --define <flag[=value]>

Define a flag e. g., EPEL7. A flag can either just be activated using flag or set to a value using flag=value. --display-flags shows available flags.

-k, --checksum <md5|sha1|sha224|sha256|sha384|sha512>

Algorithm used for checksum.

-L, --local-repo <rpm directory>

Directory with rpms to install together with reviewed package during build and install phases.

-m, --mock-config <configuration>

Specify which mock config to use, one of the files in /etc/mock, with the .cfg suffix stripped. Defaults to the root defined in /etc/mock/default.cfg

-o, --mock-options options...

Mock options for the build. Defaults to --no-cleanup-after --no-clean, you might want this along with other options you provide.

--no-report

Do not generate the review template.

--no-build

Do not rebuild or install the source rpm, instead use the last installed package available in mock. Implies --cache.

--other_bz

Url of alternative bugzilla, instead of using default https://bugzilla.redhat.com

-p, --prebuilt

When using -n <name>, use prebuilt rpms in current directory instead of building new ones in mock

-P, --plugins

Normally, the right plugin(s) to run are autodetected. Using --plugins overrides the decision to run a plugin or not. The argument is a comma-separated list of plugins, each possibly with a :off suffix e. g.,

--plugins Java:off,C/C++

Use --display-plugins to see available plugins. Enabling plugins has no well-defined semantics: some tests might leave no trace in the report even though they are actually run.

-r, --rpm-spec

Instead of using a spec file URL, use the spec file bundled in the srpm file.

-s test, --single test

Run a single test, as listed by --display-checks. Does not run dependencies, only the given test.

-v, --verbose

Provides a more detailed output of what's going on.

-x test1, test2, ... , --exclude test1, test2, ...

Comma-separated list of test(s) to exclude, as listed by --display-checks. A test which depends on an excluded test, will run.

The Review Directory

The review directory is created with a name corresponding to the command line options. The package name is always part of the name, sometimes also the bug number. Here is:

review.txt: The review template
report.xml: Report with failed issues based on the firehose xml format. This is as yet experimental and not stable. See https://github.com/fedora-static-analysis/firehose.
srpm directory: Holds whats downloaded, normally a src.rpm and a spec file. When using --rpm-spec, here is no .spec file.
srpm-unpacked directory: Holds the unpacked content of the src.rpm file.
upstream directory: contains sources downloaded from the Source: url in the spec file.
upstream-unpacked directory: Occasionally contains the unpacked sources, but is normally empty.
dependencies: Used for dependencies specfiles when EXARCH flag is set, otherwise empty.
BUILD link: Points to the mock directory containing the sources used in the build. These sources have been created and modified by the %prep stuff in the spec file. The link is only valid direct after the run, it's overwritten next time mock executes.
results directory: Contains the result from the build, logs and rpm packages.

Local Sources (Git-Based or Similar)

Normally, the Source0 (or others SourceX) in the specfile contains an URL to the upstream source. fedora-review uses this url to download the upstream source and then compare md5sum with source in rpm.

However, in some cases the Source0: is just a filename e. g., when sources are generated from git, svn or similar tools. In these cases, fedora-review will look for a file matching the Source0 in current directory. If it exists, it's used as upstream source. This way, a reviewer can generate the source according the comments in the spec before running fedora-review and then have it checked.

Using Koji Scratch Builds

It's possible to use koji to build packages instead of mock when using fedora-review. The basic idea is to run a koji scratch build, download the built packages and invoke fedora-review on these. This workflow uses the --prebuilt option, and has some limitations on checks performed since fedora-review cannot access the build directories.

The workflow:

Invoke koji, note the task number:
koji build --scratch my-package.src.rpm
Download the results:
koji-download-scratch <task number>
Invoke fedora-review using --prebuilt, --name options and --rpm-spec:
fedora-review --rpm-spec --prebuilt --name my-package

URL limitations

fedora-review handles two types of URLs: the spec and srpm url found in e. g., the bugzilla page and the source url(s) found in the spec file.

For the srpm and spec file url:

The parameters (i. e., the ? and everything beyond) is removed.
The rest must end with /*.spec or /*.src.rpm

For the source url, possible parameters are not removed. It must end with /filename, typically something like /package-2.0.1.tar.gz

Examples

Make a report template for Fedora bug 817271:

$ fedora-review -b 817271

fetches spec and srpm file from bugzilla.redhat.com and makes a report. To instead handle a bug at rpmfusion use something like

$ fedora-review --url \
https://bugzilla.rpmfusion.org/show_bug.cgi?id=2150 \
--mock-config fedora-16-i386-rpmfusion_free

Occasionally, fedora-review isn't able to pick up the links e. g., when the links does not end in .spec and/or .src.rpm. In these case you need to download files manually. Using --rpm-spec only the srpm is needed:

    $ wget https://somewhere.com/bad-srpmlink -O my-package-1.2-1.fc16.src.rpm
    $ fedora-review --rpm-spec -n my-package-1.2-1.fc16.src.rpm

You can use this command to run a review against a COPR build with a given ID (the ID 670893 is just an example one):

    $ fedora-review --copr-build 670893

Files

~/.cache/fedora-review.log: Debug logging from last session.
/usr/share/fedora-review/plugins: System-wide python plugins directory
/usr/share/fedora-review/scripts: System-wide scripts directory
~/.local/share/fedora-review/plugins/: User supplied directory for python plugins
~/.local/share/fedora-review/scripts/: User supplied directory with shell-based plugins

Environment

REVIEW_LOGLEVEL: loglevel used when not using -v/--verbose. A logging.* value like 'DEBUG', 'Info', or 'warning'. Setting REVIEW_LOGLEVEL to 'debug' is the same as providing the -v/--verbose option.
REVIEW_NO_MOCKGROUP_CHECK: Normally, fedora-review checks that user is member of the mock group before proceeding since this is required to run mock in most setups. In cases this check is not useful it can be suppressed by this variable.
XDG_DATA_HOME: fedora-review respects XDG_DATA_HOME which defaults to ~/.local/share. E. g., the personal data directory with plugins is by default ~/.local/share/fedora-review/plugins, but is $XDG_DATA_HOME/fedora-review/plugins if XDG_DATA_HOME is set. See Files.
XDG_CACHE_HOME: If set, defines the directory where the logfile fedora-review.log is written. Defaults to ~/.cache.

Authors

Original author: Tim Lauridsen <tim.lauridsen@gmail.com>

Developers:
Pierre-Yves Chibon <pingou@pingoured.fr>
Alec Leamas <leamas.alec@maybe.gmail>
Stanislav Ochotnicky <sochotnicky@redhat.com>

For a list of all contributors see AUTHORS file