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>
This commit is contained in:
Felix Moessbauer 2023-05-03 06:05:57 +02:00 committed by Jan Kiszka
parent a206f05616
commit 88964d63b5
3 changed files with 51 additions and 7 deletions

View File

@ -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 kas will refuse any other combination in order to avoid complications and
configuration flaws that can easily emerge from them. 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 Configuration reference
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~

View File

@ -123,9 +123,10 @@ class IncludeHandler:
The includes are read and merged from the deepest level upwards. 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): def __init__(self, top_files, top_repo_path, use_lock=True):

View File

@ -29,9 +29,12 @@
files. The output of this command can be used to further analyse the build files. The output of this command can be used to further analyse the build
configuration. 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. 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: Please note:
@ -48,14 +51,16 @@
kas build kas-project-expanded.yml 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 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 kas build kas-project.yml
Note, that the lockfiles should be checked-in into the VCS.
""" """
import logging import logging