Merge lp:~kissiel/checkbox/fix-1568759-default-config-name into lp:checkbox

[Maciej Kisielewski]

This MR cleans up the config files story.

Recommended read for anyone using checkbox-cli and/or launchers.

611a585 checkbox-ng:launchers: make checkbox.conf the default config name
67de921 checkbox-ng:docs: add configs' values resolution order doc
7c686a6 checkbox-ng:docs: mention configs in launcher tutorial

[Paul Larson (pwlars)]

A few minor corrections and a suggestion. Otherwise, looks good.

review: Needs Fixing

[lp:~kissiel/checkbox/fix-1568759-default-config-name]

4301. By Maciej Kisielewski on 2016-04-13

checkbox-ng:docs: make checkbox.conf the default config name

Signed-off-by: Maciej Kisielewski <email address hidden>

4302. By Maciej Kisielewski on 2016-04-13

checkbox-ng:docs: add configs' values resolution order doc

Signed-off-by: Maciej Kisielewski <email address hidden>

4303. By Maciej Kisielewski on 2016-04-13

checkbox-ng:docs: mention configs in launcher tutorial

Fixes: https://bugs.launchpad.net/plainbox/+bug/1568759

Signed-off-by: Maciej Kisielewski <email address hidden>

[Maciej Kisielewski (kissiel)]

Corrected, squashed, repushed.

[Paul Larson (pwlars)]

+1

review: Approve

=== modified file 'checkbox-ng/checkbox_ng/launcher.py'
--- checkbox-ng/checkbox_ng/launcher.py	2016-03-22 16:12:19 +0000
+++ checkbox-ng/checkbox_ng/launcher.py	2016-04-13 14:41:08 +0000
@@ -52,7 +52,7 @@
 
     config_filename = config.Variable(
         section="config",
-        default="canonical-certification.conf",
+        default="checkbox.conf",
         help_text=_("Name of custom configuration file"))
 
     def get_concrete_launcher(self):

=== added file 'checkbox-ng/docs/configs.rst'
--- checkbox-ng/docs/configs.rst	1970-01-01 00:00:00 +0000
+++ checkbox-ng/docs/configs.rst	2016-04-13 14:41:08 +0000
@@ -0,0 +1,46 @@
+Configuration values resolution order
+=====================================
+
+The directories that are searched for config files are:
+``/etc/xdg/``
+``~/.config/``
+
+The filename that's looked up depends on how checkbox is run.
+
+Invoking ``checkbox-cli`` (without launcher)
+--------------------------------------------
+Assumed config file name is ``checkbox.conf``
+
+Invoking ``plainbox``
+---------------------
+Assumed config file name is ``plainbox.conf``
+
+Invoking launcher that uses 'the new syntax'
+--------------------------------------------
+The file name to look for is specified using ``config_filename`` variable from
+launcher, from the ``[config]`` section. If it's not present, ``checkbox.conf``
+' is used.
+
+Invoking 'legacy' launcher
+--------------------------
+Both, ``plainbox.conf`` and the value ``config_filename`` from launcher are used.
+
+Apps using SessionAssistant or the plainbox internals directly
+-----------------------------------------------------------
+``plainbox.conf`` is used, unless
+``SessionAsistant.use_alternate_configuration()`` is called.
+
+Note that if same configuration variable is defined in more then one place, the
+value resolution is as follows:
+ 1. launcher being invoked (only the new syntax launchers)
+ 2. config file from ``~/.config``
+ 3. config file from ``/etc/xdg``
+
+For legacy launchers, because two config filenames can be used (the one defined
+in ``config_filename``, and ``plainbox.conf``), the one from
+``config_filename`` takes precedence over plainbox.conf. I.e. the order of
+preference is (most important first):
+ 1. ``~/.config/checkbox.conf``
+ 2. ``~/.config/plainbox.conf``
+ 3. ``/etc/xdg/checkbox.conf``
+ 4. ``/etc/xdg/plainbox.conf``

=== modified file 'checkbox-ng/docs/index.rst'
--- checkbox-ng/docs/index.rst	2014-09-16 12:53:41 +0000
+++ checkbox-ng/docs/index.rst	2016-04-13 14:41:08 +0000
@@ -58,6 +58,7 @@
    scripts/index.rst
    profiles.rst
    launcher-tutorial.rst
+   configs.rst
    release.rst
 
 Indices and tables

=== modified file 'checkbox-ng/docs/launcher-tutorial.rst'
--- checkbox-ng/docs/launcher-tutorial.rst	2016-03-22 16:24:13 +0000
+++ checkbox-ng/docs/launcher-tutorial.rst	2016-04-13 14:41:08 +0000
@@ -13,6 +13,32 @@
 
 This tutorial describes Launchers version 1.
 
+External configuration files
+============================
+
+Launcher can specify external file(s) to load values from.
+
+``[config]``
+
+Beginning of the configuration section.
+
+``config_filename``
+
+Name of the configuration file to look for. Default value: ``checkbox.conf``
+
+The directories that will be searched for the file are ``/etc/xdg/`` and
+``~/config/``.
+
+Example::
+
+    [config]
+    config_filename = testing.conf
+
+This will make checkbox look for ``/etc/xdg/testing.conf`` and
+``~/config/testing.conf`` files.
+
+For more details about value resolution order see :doc:`configs</configs>`
+
 Launcher meta-information
 =========================