doc/email/configuration.txt

1 Overview
~~~~~~~~~~

aiaiai-email scripts can be configured using the configuration file, which
includes many options for customizing the behavior of the aiaiai testing
process. Most of these values are specified "per-project" which allows the
ability for a single aiaiai-email setup to handle multiple different
repositories or kernels. This document describes and explains each
configuration option, and also includes some sections specific to complex
settings.

The configuration file is in INI format, and generally is designed to be human
editable. Each section will be described below.

2.1 Global Settings
~~~~~~~~~~~~~~~~~~~

The global configuration settings are recognized by various email scripts,
though mostly have to deal with aiaiai-email-test-patchset.

* ownname
* ownmail
    These settings change the name and email address which the scripts will
    reply as.
* adminname
* adminmail
    The address to reply to when attempting to contact a real person about the
    aiaiai-email setup. It will also modify the reply-to email header so that
    replies by default go to the administrator.
* workdir
    Temporary location used to store kernel trees for compiling, as well as
    other various temporary files generated by the aiaiai-email scripts
* max_validators
    The maximum number of validators to run in parallel. This can be used to
    allow concurrent validation of different patches or patch series at the
    same time. Be careful to ensure your test machine has enough CPU to handle
    extra validators.
* jobs
    Passed directly into the make commands, which allows make to parallelize
    its proccess. Not to be confused with the max_validators parameter. Be
    careful to ensure you have enough CPU for this.
* preamble
    Location of a file which contains text. This text is used to supply the
    start of every email sent by the aiaiai-email-scripts. Useful to customize
    the header of each email, or to provide information for users about what
    the system is for.
* signature
    A line of text to end every email sent by aiaiai. Don't end with
    punctuation, as the email script will add suitable punctuation for you.
* built_preamble
    A line of text that is inserted if the patch or series passes the
    validation without error. Don't end with puncuation as aiaiai does this for
    you.

2.2 Debug Settings
~~~~~~~~~~~~~~~~~~

These settings are generally not useful, but can be helpful for debugging
issues with aiaiai email scripts. These have replaced options which used to
perform the same behavior.

* disable_notifications
    This option disables all emails sent by the email scripts. Their contents
    will still be displayed in the stdout of the respective process, but no
    actual replies will be sent. This replaces the old "--test-mode" command line
    option. This is useful to prevent spam emails from being generated when
    testing changes to aiaiai
* preserve_files
    This option modifies the behavior so that no files will be cleaned up on
    exit. Very useful if you need to inspect individual results or generated
    files. This replaces the old "-p" option.

2.3 Default Project Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Settings described here can either appear in the [defaults] section or in the
[prj_<project>] sections, where <project> specifies a project name. A project
is specified when sending the email to a special address. For example, if the
aiaiai address is "aiaiai@aiaiai.net" then you can send the email to
"aiaiai+project@aiaiai.net" which aiaiai can extract the +project to determine
which project to use for that patch series. See the README for more information
about projects.

The per-project settings always override the default settings, and are not
additive.

* configs
    A space seperated list of defconfig,arch,cross-compiler (no spaces). The
    arch and cross-compiler are optional. Defconfig name should reside inside
    the kernel, or possibly inside the defconfigdir as specified by other
    option. Multiple configs are supported by seperating with spaces. Each
    config will be tested. See the example-aiaiai.cfg for details and examples.
* always_cc
    A comma seperated list of addresses to always Cc when creating replies. For
    example, it could be a mailing list to which all aiaiai replies go.
* reply_to_all
    A boolean (0 or 1) indicating whether to reply to all addresses or only the
    original sender.
* accept_notify
    A boolean (0 or 1) indicating whether to send an acceptance mail which
    tells the submitter that aiaiai has begun work on the patch or series.
* unwanted_keywords
    Path to a file containing unwanted keywords (one keyword per line). Aiaiai
    will check the patch against this list and notify if any keywords were
    found. This might be useful to help prevent some internal confidential
    names don't leak through commit messages or commentaries.
* kmake_opts
    A list of additional kernel build options which are appended to the make
    command used to compile the kernel. Useful to change the level of warnings,
    for example.
* targets
    A list of kernel build targets, space seperated. Note that all is only
    implicit if the target lits is empty. If you assign a value, such as
    namespacecheck, then all is not included by default and you will have to
    add it to the list.
* defconfigdir
    Path to a directory containing the defconfigs. Useful if your
    configurations are not included in the kernel tree. If you specify a
    defconfigdir, then all configurations must reside in it, as aiaiai will not
    check the kernel directory for configs.
* bisectability
    A boolean (0 or 1) indicating whether to check if patch series can be
    compiled inbetween each patch. Useful to ensure that patch series don't
    break git-bisect.
* sparse
    A boolean (0 or 1) indicating whether to use the sparse tool during static
    analysis.
* smatch
    A boolean (0 or 1) indicating whether to use the smatch tool during static
    analysis.
* cppcheck
    A boolean (0 or 1) indicating whether to use the cppcheck tool during static
    analysis.
* coccinelle
    A boolean (0 or 1) indicating whether to use the coccinelle scripts during
    static analysis.
* checkpatch
    A boolean (0 or 1) indicating whether to use checkpatch.pl for testing
    patches. Requires kernel project with checkpatch provided.

The following options do not have default settings per project and must be
specified for each project.

* name
    A human readable name for the project
* description
    A short one line projet description, that should start with a lowercase letter.
* path
    Path to the kernel source tree of the project. Note aiaiai does not treat
    this directory as read-only, and never changes anything htere. This does
    mean that aiaiai does not automatically update the tree for you. You could
    use something like a cronjob to update the tree, or any other method. It
    also does not depend on the tree being (or not) bare, so you can feel free
    to make this a bare remote or a local tree. Generally, aiaiai works best if
    the tree is locally stored on the same machine as the aiaiai process.
* branch
    What git refspec to validate against. Usually this should be a remote
    branch ie: origin/master, but can actually be any refspec. Note that the
    defconfigs specified in the config option must actually be available from
    the refspec.
* canonical_url
    The url to use when displaying a url for user consumption. Intended to be a
    patch-submitter visible mirror of the local path used internally. If not
    supplied, aiaiai will display the path instead.

2.4 Hooks
~~~~~~~~~

The [hooks] section contains settings for various points where a hook can be
run to customize the behavior of aiaiai. Generally, hooks should output
mbox-style headers, which the aiaiai program will parse for required
information. Only certain headers are supported, outlined below.

A hook is expected to return zero for successful runs, 127 for patch rejection,
and any other non zero value at run-time error. In addition, for a zero return
status, the output should be a list of headers outlined below, (one per line)
which will be parsed by aiaiai for customizing behavior. For 127 exit status,
the stdout will be used for creating a subsequent response email, and it should
contain information explaining to the user why the hook rejected the patch. For
other non-zero exit status, the output is ignored.

Hooks are passed the configuration file, and the mbox file for processing and
therefor have full access to the configuration file. Discretion should be used
if adding custom variables to the configuration file such that the hook won't
have a namespace collission with regular aiaiai configuration options.

The only currently supported hook is the email hook configured by setting
hooks.email to the path of an executable script.

2.4.1 Email Hook
~~~~~~~~~~~~~~~~

This hook is run from within aiaiai-email-test-patchset, and is run just prior
to determining the project. This hook can be used to customize the behavior and
settings of aiaiai-email-test-patchset. Primarily it can be used to implement
any kind of patch-rejection scheme desired, as well as use the following
headers to customize various aspects of aiaiai.

* X-Aiaiai-Project
    This header indicates to email-test-patchset which project the patch series
    belongs to. This overrides the default +prj format from the cfg_ownmail
    address. This can be used to implement any elaborate scheme desired for
    determining the project, instead of relying on users mailing patches to the
    correct email address.

* X-Aiaiai-Commit
    This header indicates what commit to test against instead of the default
    refspec supplied by the project. It can be used to implement some form of
    patch-version detection, or other setup. It likely should be used in tandem
    with the X-Aiaiai-Project setting.