improve documentation of lockfile support

This patch improves the documentation regarding how lockfiles work, where
kas searches for them and how to create/update them. A dedicated section
about the locking mechanism is added to the userguide. The documentation
of the kas internal logic is improved by making the wordings more precise
(e.g. lockspec vs. lockfile).

Signed-off-by: Felix Moessbauer <felix.moessbauer@siemens.com>
[Jan: fixed overlong lines]
Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>

docs/userguide.rst

@@ -273,6 +273,44 @@ come from the same repository or have to live outside of any versioning control.
 kas will refuse any other combination in order to avoid complications and
 configuration flaws that can easily emerge from them.
 
+Working with lockfiles
+~~~~~~~~~~~~~~~~~~~~~~
+
+KAS supports the use of lockfiles to pinpoint repositories to exact refspecs
+(e.g. SHA-1 refs for git). A lockfile hereby only overrides the refspecs
+defined in a kas file. When performing the checkout operation (or any other
+operation that performs a checkout), kas checks if a file named
+``<filename>.lock.<ext>`` is found next to the first file stated on the kas
+cmdline. If this is found, kas appends this filename to the kas cmdline and
+performs the requested operation.
+
+The following example shows this mechanism for a file ``kas/kas-isar.yml``
+and its corresponding lockfile ``kas/kas-isar.lock.yml``.
+
+ ``kas/kas-isar.yml``:
+
+.. code-block:: yaml
+
+  # [...]
+  repos:
+    isar:
+      url: https://github.com/ilbers/isar.git
+      refspec: next
+
+``kas/kas-isar.lock.yml``:
+
+.. code-block:: yaml
+
+  header:
+    version: 14
+  overrides:
+    repos:
+      isar:
+        refspec: 0336610df8bb0adce76ef8c5a921c758efed9f45
+
+The ``dump`` plugin provides helpers to simplify the creation and update
+of lockfiles. For details, see the plugins documentation: :mod:`kas.plugins.dump`.
+
 Configuration reference
 ~~~~~~~~~~~~~~~~~~~~~~~
 

kas/includehandler.py

@@ -123,9 +123,10 @@ class IncludeHandler:
 
         The includes are read and merged from the deepest level upwards.
 
-        In case ignore_lock is false, kas checks if a file <file>.lock.<ext>
+        In case ``ignore_lock`` is ``false``, kas checks if a file
-        exists next to the first entry in top_files. This file is then appended
+        ``<file>.lock.<ext>`` exists next to the first entry in
-        to the list of top_files.
+        ``top_files``. This filename is then appended to the list of
+        ``top_files``.
     """
 
     def __init__(self, top_files, top_repo_path, use_lock=True):

kas/plugins/dump.py

@@ -29,9 +29,12 @@
     files. The output of this command can be used to further analyse the build
     configuration.
 
-    When running with --lock, a lock-file is created which only contains the
+    When running with ``--lock``, a locking spec is created which only contains
-    exact refspecs of each repository. This file can be used to pin the
+    the exact refspecs of each repository. This can be used to pin the
     refspecs of floating branches, while still keeping an easy update path.
+    When combining with ``--inplace``, a lockfile is created next to the
+    first file on the kas cmdline. For details on the locking support, see
+    :class:`kas.includehandler.IncludeHandler`.
 
     Please note:
 
@@ -48,14 +51,16 @@
 
         kas build kas-project-expanded.yml
 
-    Example of the locking mechanism (call again to regenerate lockfile):
+    Example of the locking mechanism (call again to regenerate lockfile).
+    The lockfile is created as ``kas-project.lock.yml``::
 
         kas dump --lock --inplace --update kas-project.yml
 
-    The generated lockfile will automatically be used to pin the revisions:
+    The generated lockfile will automatically be used to pin the revisions::
 
         kas build kas-project.yml
 
+    Note, that the lockfiles should be checked-in into the VCS.
 """
 
 import logging