Add a quick-start guide incl. a template conf

Signed-off-by: Niels Thykier <niels@thykier.net>

README.md

@@ -5,15 +5,35 @@ by feeding it updates from (one or more) source-suite(s).  A few known use
 cases:
 
  * Debian uses it to update testing based on unstable
- * Ubuntu uses it to update their latest development suite using a "hidden" -proposed suite as source
+ * Ubuntu uses it to update their latest development suite using a "hidden" -proposed-updates suite as source
 
 Britney's primary goal is too keep packages in the target suite installable
-(e.g. Debian testing) while keeping it up to daye with its primary source
+(e.g. Debian testing) while keeping it up to date with its primary source
 suite (e.g. Debian unstable).
 
 ## Quick setup guide
 
-TODO: Write a quick setup guide (once mirror layout has been tested)
+This is a very brief intro to the steps required to setup a
+Britney instance.
+
+ * Copy "britney.conf.template" and edit it to suit your purpose
+    - If you want Britney to bootstrap your target suite, you
+      probably want to add all architectures to "NEW_ARCHES" and
+      "BREAK_ARCHES" for a few runs
+ * Create the following files (they can be empty):
+    - $STATE_DIR/age-policy-dates
+    - $STATE_DIR/age-policy-urgencies
+    - $STATE_DIR/rc-bugs-unstable
+    - $STATE_DIR/rc-bugs-testing
+ * Run ```./britney.py -c $BRITNEY_CONF -v [--dry-run]``` to test the run
+ * Use the resulting $HEIDI_OUTPUT (or $HEIDI_DELTA_OUTPUT) to update
+   your target suite.
+    - With dak, ```cut -d" " -f1-3 < ${HEIDI_OUTPUT} | dak control-suite --set ${TARGET_SUITE} [--britney]```
+ * Setup a cron-/batch-job that:
+    - (Optionally) Updates the rc-bugs files
+    - (Optionally) Updates the $STATE_DIR/age-policy-urgencies
+    - Runs Britney
+    - Imports the result into your target suite
 
 ## Migration items
 
@@ -22,14 +42,14 @@ packages (and possibly a source package).  Packages are bundled into these
 migration items under the following rules:
 
  1. "source migration": An update of the source package.  This will include all the binary packages built from that source version (regardless of architecture).
-   * Can contain binaries built from earlier source version depending on the setting of "IGNORE_CRUFT"
-   * Britney refers to these as "${SOURCE_NAME}"
+    * Can contain binaries built from earlier source version depending on the setting of "IGNORE_CRUFT"
+    * Britney refers to these as "${SOURCE_NAME}"
  1. "binary migration": An update of binary packages on a given architecture to an existing source package in the target suite.
-   * Two common cases: Built for the first time on a new architecture and binNMUs
-   * Britney refers to all cases of these as "${SOURCE_NAME}/${ARCHITECTURE}"
+    * Two common cases: Built for the first time on a new architecture and binNMUs
+    * Britney refers to all cases of these as "${SOURCE_NAME}/${ARCHITECTURE}"
  1. "removal item": A removal of a source or binary package.
-   * Note that it is only possible to trigger "source" removals via hints.  Binary removals are items generated by Britney to clean up the target suite.
-   * Britney refers to these as "-${SOURCE_NAME}" or "-${BINARY_NAME}/${ARCHITECTURE}" depending on the case.
+    * Note that it is only possible to trigger "source" removals via hints.  Binary removals are items generated by Britney to clean up the target suite.
+    * Britney refers to these as "-${SOURCE_NAME}" or "-${BINARY_NAME}/${ARCHITECTURE}" depending on the case.
 
 ## Migration rules (excuses/policies)
 

britney.conf.template

@@ -0,0 +1,98 @@
+#  Template configuration file for britney
+
+# Paths to suites in a local mirror
+# Note: Britney will only need metadata files and not the debs/dscs
+# themselves.
+UNSTABLE          = /path/to/source/suite
+TESTING           = /path/to/target/suite
+# Items in these two suites will require manual approval
+TPU               = /path/to/secondary-source/suite
+# Optional suite
+# PU                = /path/to/another-source/suite
+
+# List of components to work with
+COMPONENTS        = main, non-free, contrib
+
+# Output
+NONINST_STATUS      = /path/to/britneys-output-dir/non-installable-status
+EXCUSES_OUTPUT      = /path/to/britneys-output-dir/excuses.html
+EXCUSES_YAML_OUTPUT = /path/to/britneys-output-dir/excuses.yaml
+UPGRADE_OUTPUT      = /path/to/britneys-output-dir/output.txt
+HEIDI_OUTPUT        = /path/to/britneys-output-dir/HeidiResult
+HEIDI_DELTA_OUTPUT  = /path/to/britneys-output-dir/HeidiResultDelta
+
+# External policy/constraints/faux-packages information that
+# (presumably) rarely changes.  Examples include "constraints".
+# STATIC_INPUT_DIR = /path/to/static/input
+
+# Directory for input files that Britney will update herself
+# (e.g. aging information) or will need regular updates
+# (e.g. urgency information).
+STATE_DIR          = /path/to/britey/state-dir
+
+# List of architectures Britney should consider
+ARCHITECTURES     = i386 amd64 arm64 armel armhf mips mipsel powerpc ppc64el s390x
+
+# if you're not in this list, arch: all packages are allowed to break on you
+NOBREAKALL_ARCHES = i386 amd64
+
+# if you're in this list, your packages may not stay in sync with the source
+FUCKED_ARCHES     =
+
+# if you're in this list, your uninstallability count may increase
+BREAK_ARCHES      =
+
+# if you're in this list, you are a new architecture
+NEW_ARCHES        =
+
+# For the aging policy - all "MINDAYS_X" are measured in days
+MINDAYS_LOW       = 10
+MINDAYS_MEDIUM    = 5
+MINDAYS_HIGH      = 2
+MINDAYS_CRITICAL  = 0
+MINDAYS_EMERGENCY = 0
+# The urgency to assume if none is provided or it is not defined with
+# a MINDAYS_$NAME config above
+DEFAULT_URGENCY   = medium
+
+# Directory where hints files are stored
+HINTSDIR = /path/to/britney/hints-dir
+
+# hint permissions
+# Each "HINTS_NAME" defines the list of permissions for a given hints
+# file in HINTSDIR.  The name of the hints file should be in all
+# lowercase (i.e. "HINTS_FOO" applies to the file "foo" in HINTSDIR)
+#
+#
+# HINTS_USER1         = STANDARD
+# HINTS_USER2         = STANDARD force
+# HINTS_USER3         = STANDARD force force-hint
+# HINTS_USER4         = ALL
+#
+# Possible "role" hints
+#
+# HINTS_FREEZE        = block block-all block-udeb
+# HINTS_AUTO-REMOVALS = remove
+
+# support for old libraries in testing (smooth update)
+#
+# This option makes it easier for Britney to handle transitions as she
+# will be allowed to keep old binaries around if they have reverse
+# dependencies.
+#
+# This requires that your archive tool is capable of handling binaries
+# without a source (or multiple versions of the source package in a
+# given suite).  The "old" source will *not* be listed in the output
+# for binaries that are retained like this.  DAK is known to handle
+# this and will keep the "old" source in the target distribution as
+# long as it has binaries left.
+#
+# - leave it blank to disable it
+# - use ALL to enable smooth updates for all the sections
+# - naming a non-existent section will effectively disable new
+#   smooth updates but still allow removals to occur
+SMOOTH_UPDATES    = libs oldlibs
+
+# Whether old binaries in the source distribution should be
+# considered as a blocker for migration.
+IGNORE_CRUFT      = 1