doc: add CONFIGURATION file describing the cfgfile

This patch adds a CONFIGURATION file which describes the aiaiai
configuration file. This will be expanded upon in future commits which
introduce the aiaiai hooks.

Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Signed-off-by: Artem Bityutskiy <artem.bityutskiy@linux.intel.com>

2 files changed, 164 insertions, 1 deletions

diff --git a/doc/README b/doc/README
index 544d365..28e0bca 100644
--- a/doc/README
+++ b/doc/README
@@ -105,8 +105,13 @@ The 'aiaiai-test-patchset' script does all the testing work and outputs the
 test results to stdout. 'aiaiai-email-test-patchset' captures the output and
 sends it back to the patch submitter.
 
+1.2 Email Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
 
-1.2 Non-e-mail scripts
+aiaiai-email scripts use a common configuration file, which is documented in
+doc/email/example-aiaiai.cfg
+
+1.3 Non-e-mail scripts
 ~~~~~~~~~~~~~~~~~~~~~~
 
 * aiaiai-test-patchset
diff --git a/doc/email/CONFIGURATION b/doc/email/CONFIGURATION
new file mode 100644
index 0000000..7e7af5b
--- /dev/null
+++ b/doc/email/CONFIGURATION
@@ -0,0 +1,158 @@
+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.
+* 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.
+* 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.
+
+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.
+