From 88964d63b5b212f676298bfb9c0d9177a64d4a4d Mon Sep 17 00:00:00 2001
From: Felix Moessbauer <felix.moessbauer@siemens.com>
Date: Wed, 3 May 2023 06:05:57 +0200
Subject: [PATCH] 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    | 38 ++++++++++++++++++++++++++++++++++++++
 kas/includehandler.py |  7 ++++---
 kas/plugins/dump.py   | 13 +++++++++----
 3 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/docs/userguide.rst b/docs/userguide.rst
index a6b1c5b..ae677ea 100644
--- a/docs/userguide.rst
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/kas/includehandler.py b/kas/includehandler.py
index c42b227..8d1d274 100644
--- a/kas/includehandler.py
+++ b/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>
-        exists next to the first entry in top_files. This file is then appended
-        to the list of top_files.
+        In case ``ignore_lock`` is ``false``, kas checks if a file
+        ``<file>.lock.<ext>`` exists next to the first entry in
+        ``top_files``. This filename is then appended to the list of
+        ``top_files``.
     """
 
     def __init__(self, top_files, top_repo_path, use_lock=True):
diff --git a/kas/plugins/dump.py b/kas/plugins/dump.py
index dda8ecc..e59d75c 100644
--- a/kas/plugins/dump.py
+++ b/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
-    exact refspecs of each repository. This file can be used to pin the
+    When running with ``--lock``, a locking spec is created which only contains
+    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