[PATCH 12/13] docs: Update userguide to commit/branch, dropping refspec

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Dropping all refspec references shall help new users on the right path
from the beginning.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---
docs/userguide.rst | 41 +++++++++++++++++++++++------------------
1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/docs/userguide.rst b/docs/userguide.rst
index 4bc87ae..834e4c9 100644
--- a/docs/userguide.rst
+++ b/docs/userguide.rst
@@ -138,7 +138,7 @@ arguably easier to read, this documentation focuses on the YAML format.
# bblayers.conf:
poky:
url: "https://git.yoctoproject.org/git/poky"
- refspec: 89e6c98d92887913cadf06b2adb97f26cde4849b
+ commit: 89e6c98d92887913cadf06b2adb97f26cde4849b
layers:
meta:
meta-poky:
@@ -218,7 +218,7 @@ It's also possible to include configuration files from other repos like this:
meta-custom:
meta-bsp-collection:
url: "https://www.example.com/git/meta-bsp-collection"
- refspec: 3f786850e387550fdab836ed7e6dc881de23001b
+ commit: 3f786850e387550fdab836ed7e6dc881de23001b
layers:
# Additional to the layers that are added from this repository
# in the hw1/kas-hw-bsp1.yml, we add here an additional bsp
@@ -226,7 +226,7 @@ It's also possible to include configuration files from other repos like this:
meta-custom-bsp:
poky:
url: "https://git.yoctoproject.org/git/poky"
- refspec: 89e6c98d92887913cadf06b2adb97f26cde4849b
+ commit: 89e6c98d92887913cadf06b2adb97f26cde4849b
layers:
# If `kas-poky.yml` adds the `meta-yocto-bsp` layer and we
# do not want it in our bblayers for this project, we can
@@ -276,8 +276,8 @@ 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
+KAS supports the use of lockfiles to pinpoint repositories to exact commit ID
+(e.g. SHA-1 refs for git). A lockfile hereby only overrides the commit ID
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
@@ -295,7 +295,7 @@ and its corresponding lockfile ``kas/kas-isar.lock.yml``.
repos:
isar:
url: https://github.com/ilbers/isar.git
- refspec: next
+ branch: next

``kas/kas-isar.lock.yml``:

@@ -306,7 +306,7 @@ and its corresponding lockfile ``kas/kas-isar.lock.yml``.
overrides:
repos:
isar:
- refspec: 0336610df8bb0adce76ef8c5a921c758efed9f45
+ commit: 0336610df8bb0adce76ef8c5a921c758efed9f45

The ``dump`` plugin provides helpers to simplify the creation and update
of lockfiles. For details, see the plugins documentation: :mod:`kas.plugins.dump`.
@@ -357,7 +357,7 @@ Configuration reference
* ``defaults``: dict [optional]
This key can be used to set default values for various properties.
This may help you to avoid repeating the same property assignment in
- multiple places if, for example, you wish to use the same refspec for
+ multiple places if, for example, you wish to use the same branch for
all repositories.

* ``repos``: dict [optional]
@@ -366,8 +366,8 @@ Configuration reference
overridden by setting the same property to a different value in a given
repository.

- * ``refspec``: string [optional]
- Sets the default ``refspec`` property applied to all repositories that
+ * ``branch``: string [optional]
+ Sets the default ``branch`` property applied to all repositories that
do not override this.

* ``patches``: dict [optional]
@@ -433,10 +433,15 @@ Configuration reference
The type of version control repository. The default value is ``git``
and ``hg`` is also supported.

- * ``refspec``: string [optional]
- The refspec that should be used. If ``url`` was specified but no
- ``refspec`` the revision you get depends on the defaults of the version
- control system used.
+ * ``commit``: string [optional]
+ The commit ID (branch names, no symbolic refs, no tags) that should be
+ used. If ``url`` was specified but no ``commit`` and no ``branch``, the
+ revision you get depends on the defaults of the version control system
+ used.
+
+ * ``branch``: string [optional]
+ The upstream branch that should be tracked. If no ``commit`` was
+ specified, the head of the upstream is checked out.

* ``path``: string [optional]
The path where the repository is stored.
@@ -462,7 +467,7 @@ Configuration reference
meta-foo:
url: https://github.com/bar/meta-foo.git
path: layers/meta-foo
- refspec: master
+ branch: master
layers:
.:
contrib:
@@ -505,9 +510,9 @@ Configuration reference
* ``<repo-id>``: dict [optional]
Mapps to the ``<repo-id>`` entry.

- * ``refspec``: string [optional]
- Pinned refspec which overrides the ``refspec`` of the corresponding
- repo. This refspec must be resolved (i.e. no branch or tag name).
+ * ``commit``: string [optional]
+ Pinned commit ID which overrides the ``commit`` of the corresponding
+ repo.

* ``bblayers_conf_header``: dict [optional]
This contains strings that should be added to the ``bblayers.conf`` before
--
2.35.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Adjust the wording the avoid confusion when there is no longer a refspec
key one day.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

kas/libkas.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/kas/libkas.py b/kas/libkas.py
index f9a0734..613b38a 100644
--- a/kas/libkas.py
+++ b/kas/libkas.py
@@ -412,11 +412,11 @@ def setup_parser_common_args(parser):
help='Skip build steps',
default=[])
parser.add_argument('--force-checkout', action='store_true',
- help='Always checkout the desired refspec of each '
- 'repository, discarding any local changes')
+ help='Always checkout the desired commit/branch of '
+ 'each repository, discarding any local changes')
parser.add_argument('--update', action='store_true',
help='Pull new upstream changes to the desired '
- 'refspec even if it is already checked out locally')
+ 'branch even if it is already checked out locally')


def setup_parser_preserve_env_arg(parser):
--
2.35.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Lift most test cases to the new syntax, just with few exceptions:
- tests/test_refspec/test2.yml actually stresses the mixed usage
(but clean per repo)
- tests/test_repo_includes references kas as external repo at a point
where there was no new syntax yet; this needs to be migrated
differently later on

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

image-tests/isar/kas.yml | 6 +++---
image-tests/poky/kas.yml | 6 +++---
tests/test_commands.py | 12 ++++++------
tests/test_commands/test-invalid.yml | 4 ++--
tests/test_commands/test.yml | 6 +++---
tests/test_environment_variables/test_env.yml | 6 +++---
tests/test_layers/test.yml | 10 +++++-----
tests/test_patch.py | 2 +-
tests/test_patch/test-invalid.yml | 4 ++--
tests/test_patch/test-invalid2.yml | 4 ++--
tests/test_patch/test-invalid3.yml | 4 ++--
tests/test_patch/test.yml | 10 +++++-----
tests/test_patch/test2.yml | 10 +++++-----
tests/test_refspec/test.yml | 6 +++---
tests/test_refspec/test2.yml | 5 +++--
tests/test_refspec/test3.yml | 6 +++---
16 files changed, 51 insertions(+), 50 deletions(-)

diff --git a/image-tests/isar/kas.yml b/image-tests/isar/kas.yml
index f728d7e..41ace23 100644
--- a/image-tests/isar/kas.yml
+++ b/image-tests/isar/kas.yml
@@ -1,7 +1,7 @@
#
# kas - setup tool for bitbake based projects
#
-# Copyright (c) Siemens AG, 2022
+# Copyright (c) Siemens AG, 2022-2023
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
@@ -23,7 +23,7 @@
#

header:
- version: 11
+ version: 14

build_system: isar

@@ -35,7 +35,7 @@ target: mc:qemuamd64-bullseye:cowsay

repos:
isar:
url: https://github.com/ilbers/isar.git

- refspec: 8dfa97cf6e25a7adec2e02c50c5ef6329f31931b
+ commit: 8dfa97cf6e25a7adec2e02c50c5ef6329f31931b
layers:
meta:
meta-isar:
diff --git a/image-tests/poky/kas.yml b/image-tests/poky/kas.yml
index 50ffa15..1fce47f 100644
--- a/image-tests/poky/kas.yml
+++ b/image-tests/poky/kas.yml
@@ -1,7 +1,7 @@
#
# kas - setup tool for bitbake based projects
#
-# Copyright (c) Siemens AG, 2022
+# Copyright (c) Siemens AG, 2022-2023
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
@@ -23,14 +23,14 @@
#

header:
- version: 11
+ version: 14

target: zlib-native

repos:
poky:
url: https://git.yoctoproject.org/poky.git
- refspec: 387ab5f18b17c3af3e9e30dc58584641a70f359f
+ commit: 387ab5f18b17c3af3e9e30dc58584641a70f359f
layers:
meta:
meta-poky:
diff --git a/tests/test_commands.py b/tests/test_commands.py
index 9f76598..6a130ed 100644
--- a/tests/test_commands.py
+++ b/tests/test_commands.py
@@ -113,7 +113,7 @@ def test_dump(changedir, tmpdir, capsys):

with open(outfile, 'r') as cf:
flatconf = json.load(cf) if f == 'json' else yaml.safe_load(cf)
- refspec = flatconf['repos']['kas3']['refspec']
+ refspec = flatconf['repos']['kas3'].get('refspec', None)
envvar = flatconf['env']['TESTVAR_FOO']
if r == '--resolve-refs':
assert refspec != 'master'
@@ -156,9 +156,9 @@ def test_lockfile(changedir, tmpdir, capsys):
assert lockspec['overrides']['repos']['externalrepo']['commit'] \
== expected_commit

- # insert older refspec into lockfile (kas 3.2 tag)
- test_refspec = 'dc44638cd87c4d0045ea2ca441e682f3525d8b91'
- lockspec['overrides']['repos']['externalrepo']['commit'] = test_refspec
+ # insert older commit into lockfile (kas 3.2 tag)
+ test_commit = 'dc44638cd87c4d0045ea2ca441e682f3525d8b91'
+ lockspec['overrides']['repos']['externalrepo']['commit'] = test_commit
with open('test.lock.yml', 'w') as f:
yaml.safe_dump(lockspec, f)

@@ -166,11 +166,11 @@ def test_lockfile(changedir, tmpdir, capsys):
kas.kas('dump test.yml'.split())
lockspec = yaml.safe_load(capsys.readouterr().out)
assert lockspec['overrides']['repos']['externalrepo']['commit'] \
- == test_refspec
+ == test_commit

# update lockfile, check if repo is pinned to other commit
kas.kas('dump --lock --inplace --update test.yml'.split())
with open('test.lock.yml', 'r') as f:
lockspec = yaml.safe_load(f)
assert lockspec['overrides']['repos']['externalrepo']['commit'] \
- != test_refspec
+ != test_commit
diff --git a/tests/test_commands/test-invalid.yml b/tests/test_commands/test-invalid.yml
index 79004ab..872e0da 100644
--- a/tests/test_commands/test-invalid.yml
+++ b/tests/test_commands/test-invalid.yml
@@ -1,7 +1,7 @@
header:
- version: 8
+ version: 14

repos:
kas_invalid:
url: https://example.com/kas.git
- refspec: this-ref-is-invalid
+ branch: this-ref-is-invalid
diff --git a/tests/test_commands/test.yml b/tests/test_commands/test.yml
index 382cc66..619cd52 100644
--- a/tests/test_commands/test.yml
+++ b/tests/test_commands/test.yml
@@ -1,13 +1,13 @@
header:
- version: 8
+ version: 14

repos:
this:

kas_1.0:
url: https://github.com/siemens/kas.git
- refspec: 907816a5c4094b59a36aec12226e71c461c05b77
+ commit: 907816a5c4094b59a36aec12226e71c461c05b77

kas_1.1:
url: https://github.com/siemens/kas.git
- refspec: e9ca55a239caa1a2098e1d48773a29ea53c6cab2
+ commit: e9ca55a239caa1a2098e1d48773a29ea53c6cab2
diff --git a/tests/test_environment_variables/test_env.yml b/tests/test_environment_variables/test_env.yml
index 1cf50d7..750ffae 100644
--- a/tests/test_environment_variables/test_env.yml
+++ b/tests/test_environment_variables/test_env.yml
@@ -1,5 +1,5 @@
header:
- version: 13
+ version: 14

env:
TESTVAR_DEFAULT_VAL: "BAR"
@@ -13,13 +13,13 @@ repos:
# Testing new BB_ENV_PASSTHROUGH_ADDITIONS
bitbake_new:
url: https://git.openembedded.org/bitbake
- refspec: 87104b6a167188921da157c7dba45938849fb22a
+ commit: 87104b6a167188921da157c7dba45938849fb22a
layers:
.: excluded

# Testing deprecated BB_ENV_WHITELIST
bitbake_old:
url: https://git.openembedded.org/bitbake
- refspec: efaafc9ec2e8c0475e3fb27e877a1c0a5532a0e5
+ commit: efaafc9ec2e8c0475e3fb27e877a1c0a5532a0e5
layers:
.: excluded
diff --git a/tests/test_layers/test.yml b/tests/test_layers/test.yml
index c8ea3d6..285a1ea 100644
--- a/tests/test_layers/test.yml
+++ b/tests/test_layers/test.yml
@@ -1,29 +1,29 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master

kas1:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master
layers:

meta-foo:
meta-bar:

kas2:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master
layers:

.: excluded

kas3:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master
layers:
.:

meta-bar:
diff --git a/tests/test_patch.py b/tests/test_patch.py
index cfb5d89..a6e4709 100644
--- a/tests/test_patch.py
+++ b/tests/test_patch.py
@@ -42,7 +42,7 @@ def test_patch(changedir, tmpdir):

def test_patch_update(changedir, tmpdir):
"""
- Test that patches are applied correctly after switching refspec from
+ Test that patches are applied correctly after switching a repo from
a branch to a commit hash and vice-versa with both git and mercurial
repositories.
"""
diff --git a/tests/test_patch/test-invalid.yml b/tests/test_patch/test-invalid.yml
index 11d4d43..3bb3554 100644
--- a/tests/test_patch/test-invalid.yml
+++ b/tests/test_patch/test-invalid.yml
@@ -1,12 +1,12 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/siemens/kas.git
- refspec: 907816a5c4094b59a36aec12226e71c461c05b77
+ commit: 907816a5c4094b59a36aec12226e71c461c05b77
patches:
plain:
repo: this
diff --git a/tests/test_patch/test-invalid2.yml b/tests/test_patch/test-invalid2.yml
index 95be172..08fd906 100644
--- a/tests/test_patch/test-invalid2.yml
+++ b/tests/test_patch/test-invalid2.yml
@@ -1,10 +1,10 @@
header:
- version: 8
+ version: 14

repos:
kas:
url: https://github.com/siemens/kas.git
- refspec: 907816a5c4094b59a36aec12226e71c461c05b77
+ commit: 907816a5c4094b59a36aec12226e71c461c05b77
patches:
plain:
repo: non-existent
diff --git a/tests/test_patch/test-invalid3.yml b/tests/test_patch/test-invalid3.yml
index 4c66a31..0617c96 100644
--- a/tests/test_patch/test-invalid3.yml
+++ b/tests/test_patch/test-invalid3.yml
@@ -1,12 +1,12 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/ilbers/isar.git
- refspec: 47aaeedecd0ea6f754da36be1d10717b04eb8275
+ commit: 47aaeedecd0ea6f754da36be1d10717b04eb8275
patches:
plain:
repo: this
diff --git a/tests/test_patch/test.yml b/tests/test_patch/test.yml
index bba55af..4d4fd18 100644
--- a/tests/test_patch/test.yml
+++ b/tests/test_patch/test.yml
@@ -1,12 +1,12 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/siemens/kas.git
- refspec: 907816a5c4094b59a36aec12226e71c461c05b77
+ commit: 907816a5c4094b59a36aec12226e71c461c05b77
patches:
plain:
repo: this
@@ -17,7 +17,7 @@ repos:

kas-branch:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master

patches:
plain:
repo: this
@@ -25,7 +25,7 @@ repos:

hello:
url: https://www.mercurial-scm.org/repo/hello/
- refspec: 82e55d328c8c
+ commit: 82e55d328c8c
type: hg
patches:
plain:
@@ -37,7 +37,7 @@ repos:

hello-branch:
url: https://www.mercurial-scm.org/repo/hello/
- refspec: default
+ branch: default
type: hg
patches:
plain:
diff --git a/tests/test_patch/test2.yml b/tests/test_patch/test2.yml
index bba27a6..48fa18e 100644
--- a/tests/test_patch/test2.yml
+++ b/tests/test_patch/test2.yml
@@ -1,12 +1,12 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master

patches:
plain:
repo: this
@@ -14,7 +14,7 @@ repos:

kas-branch:
url: https://github.com/siemens/kas.git
- refspec: 907816a5c4094b59a36aec12226e71c461c05b77
+ commit: 907816a5c4094b59a36aec12226e71c461c05b77
patches:
plain:
repo: this
@@ -25,7 +25,7 @@ repos:

hello:
url: https://www.mercurial-scm.org/repo/hello/
- refspec: default
+ branch: default
type: hg
patches:
plain:
@@ -37,7 +37,7 @@ repos:

hello-branch:
url: https://www.mercurial-scm.org/repo/hello/
- refspec: 0a04b987be5a
+ commit: 0a04b987be5a
type: hg
patches:
plain:
diff --git a/tests/test_refspec/test.yml b/tests/test_refspec/test.yml
index 7d4189f..c15d27d 100644
--- a/tests/test_refspec/test.yml
+++ b/tests/test_refspec/test.yml
@@ -1,13 +1,13 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/siemens/kas.git
- refspec: 907816a5c4094b59a36aec12226e71c461c05b77
+ commit: 907816a5c4094b59a36aec12226e71c461c05b77

kas2:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master

diff --git a/tests/test_refspec/test2.yml b/tests/test_refspec/test2.yml
index 5766e72..ae6fb4e 100644
--- a/tests/test_refspec/test2.yml
+++ b/tests/test_refspec/test2.yml
@@ -1,13 +1,14 @@
header:
- version: 8
+ version: 14

repos:
this:

kas:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master

kas2:
url: https://github.com/siemens/kas.git
+ # keep legacy refspec here for testing purposes
refspec: 907816a5c4094b59a36aec12226e71c461c05b77
diff --git a/tests/test_refspec/test3.yml b/tests/test_refspec/test3.yml
index 2557cfe..41e3859 100644
--- a/tests/test_refspec/test3.yml
+++ b/tests/test_refspec/test3.yml
@@ -1,13 +1,13 @@
header:
- version: 8
+ version: 14

repos:
this:

kas_abs:
url: https://github.com/siemens/kas.git
- refspec: refs/heads/master
+ branch: refs/heads/master

kas_rel:
url: https://github.com/siemens/kas.git

- refspec: master
+ branch: master

--
2.35.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Add corresponding environment variables for the new keys and declare the
existing KAS_REPO_REFSPEC as deprecated in lock-step with the key it
mirrors.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

kas/plugins/for_all_repos.py | 14 +++++++++++++-
1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/kas/plugins/for_all_repos.py b/kas/plugins/for_all_repos.py
index 2581ae7..b720eb2 100644
--- a/kas/plugins/for_all_repos.py
+++ b/kas/plugins/for_all_repos.py
@@ -48,9 +48,19 @@
* ``KAS_REPO_URL``: The URL from which this repository was cloned, or an
empty string if no remote URL was given in the config file.

+ * ``KAS_REPO_COMMIT``: The commit ID which was checked out for this
+ repository, or an empty string if no commit was given in the config
+ file.
+
+ * ``KAS_REPO_BRANCH``: The branch which was checked out for this
+ repository, or an empty string if no branch was given in the config
+ file.
+
* ``KAS_REPO_REFSPEC``: The refspec which was checked out for this
repository, or an empty string if no refspec was given in the config
- file.
+ file. This variable is obsolete and will be removed when support for
+ respec keys is removed as well. Migrate your repos to commit/branch
+ and use the related variables instead.
"""

import logging
@@ -107,6 +117,8 @@ class ForAllReposCommand(Command):
'KAS_REPO_NAME': repo.name,
'KAS_REPO_PATH': repo.path,
'KAS_REPO_URL': '' if repo.operations_disabled else repo.url,
+ 'KAS_REPO_COMMIT': repo.commit or '',
+ 'KAS_REPO_BRANCH': repo.branch or '',
'KAS_REPO_REFSPEC': repo.refspec or '',
}
logging.info('%s$ %s', repo.path, self.command)
--
2.35.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

This reflects the addition of commit and branch keys as well as the
switch to commit for overrides.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

docs/format-changelog.rst | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/format-changelog.rst b/docs/format-changelog.rst
index 15941cb..f093741 100644
--- a/docs/format-changelog.rst
+++ b/docs/format-changelog.rst
@@ -137,7 +137,10 @@ Version 14
Added
~~~~~

-- The ``overrides`` top-level entry can be used to pin floating repo refspecs.
+- The keys ``commit`` and ``branch`` are introduced as replacement of
+ ``refspec`` in ``repos`` and ``defaults``. ``refspec`` is now deprecated and
+ will eventually be removed.
+- The ``overrides`` top-level entry can be used to pin floating repo branches.
- ``_source_dir`` top-level entry is auto-generated when using the menu plugin
and provides the path to the top repo at time of invoking the plugin.
- ``_source_dir_host`` top-level entry is auto-generated by kas-container to
--
2.35.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Covers both the invalid combinations refspec with the new commit/branch
keys as well as the issuing of a warning when a repo contains refspec.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

tests/test_refspec.py | 24 ++++++++++++++++++++++++
tests/test_refspec/test5.yml | 10 ++++++++++
tests/test_refspec/test6.yml | 10 ++++++++++
3 files changed, 44 insertions(+)
create mode 100644 tests/test_refspec/test5.yml
create mode 100644 tests/test_refspec/test6.yml

diff --git a/tests/test_refspec.py b/tests/test_refspec.py
index 6a42aa8..e5fb07f 100644
--- a/tests/test_refspec.py
+++ b/tests/test_refspec.py
@@ -98,3 +98,27 @@ def test_url_no_refspec(changedir, tmpdir):
os.chdir(tdir)
with pytest.raises(RepoRefError):
kas.kas(['shell', 'test4.yml', '-c', 'true'])
+
+
+def test_commit_refspec_mix(changedir, tmpdir):
+ """
+ Test that mixing legacy refspec with commit/branch raises errors.
+ """
+ tdir = str(tmpdir / 'test_url_no_refspec')
+ shutil.copytree('tests/test_refspec', tdir)
+ os.chdir(tdir)
+ with pytest.raises(RepoRefError):
+ kas.kas(['shell', 'test5.yml', '-c', 'true'])
+ with pytest.raises(RepoRefError):
+ kas.kas(['shell', 'test6.yml', '-c', 'true'])
+
+
+def test_refspec_warning(capsys, changedir, tmpdir):
+ """
+ Test that using legacy refspec issues a warning, but only once.
+ """
+ tdir = str(tmpdir / 'test_url_no_refspec')
+ shutil.copytree('tests/test_refspec', tdir)
+ os.chdir(tdir)
+ kas.kas(['shell', 'test2.yml', '-c', 'true'])
+ assert capsys.readouterr().err.count('Using deprecated refspec for repository "kas2".') == 1
diff --git a/tests/test_refspec/test5.yml b/tests/test_refspec/test5.yml
new file mode 100644
index 0000000..d94dfdc
--- /dev/null
+++ b/tests/test_refspec/test5.yml
@@ -0,0 +1,10 @@
+header:
+ version: 14
+
+repos:
+ this:
+
+ kas:
+ url: https://github.com/siemens/kas.git
+ commit: dc44638cd87c4d0045ea2ca441e682f3525d8b91
+ refspec: master
diff --git a/tests/test_refspec/test6.yml b/tests/test_refspec/test6.yml
new file mode 100644
index 0000000..0332d9e
--- /dev/null
+++ b/tests/test_refspec/test6.yml
@@ -0,0 +1,10 @@
+header:
+ version: 14
+
+repos:
+ this:
+
+ kas:
+ url: https://github.com/siemens/kas.git
+ refspec: dc44638cd87c4d0045ea2ca441e682f3525d8b91

[Jan Kiszka]

This is now the 3rd or 4th attempt to deal with branch/commit ambiguity
in kas, if including the attempts to also address repo integrity
checking here. This one is a direct follow up of [1] where I tried to
resolve the refspec ambiguity by banning SHA-like branch and ref names.
Henning suggested to better do that without heuristic, so here comes it.

This series introduces the keys commit and branch to repos so that one
can clearly express if a refspec is supposed to be fixed, floating or
tracking an upstream branch but using a concrete commit ID. Every of the
so far presented approaches had it benefits and shortcoming. Pros here:
- no commit ID detection heuristics, clear semantics
- permitting to define a local tracking branch [2]
- no attempt to offload the integrity check from upstream git or hg,
i.e. no checksums

Cons are:
- need to change layers eventually to be able to drop refspec
- complexity, specifically while both new and old formats are both
around

My rough plan would be to get this in before the next release, which is
likely going to be 4.0 with the image switch to bookworm. Then, after a
year or maybe even longer, drop refspec from the schema, making that
version no longer backward compatible.

Happy to hear your opinions and get your review.

Jan

[1] https://groups.google.com/g/kas-devel/c/IuR_0dm5bpM/m/LxRffCiDDgAJ
[2] https://groups.google.com/g/kas-devel/c/QJu1va7Mriw/m/-eAFklTLAQAJ


CC: Aditya Sirish A Yelgundhalli <adi...@saky.in>
CC: Felix Moessbauer <felix.mo...@siemens.com>
CC: Henning Schild <henning...@siemens.com>
CC: Jan Kircher <jan.k...@leica-microsystems.com>

Jan Kiszka (13):
repos: Rename boolean branch variable/argument to is_branch
repos: git: Strip of heads/ prefix when checking out branches
repos: git: Always replicate refs/ into local branches on checkout
repos: hg: Add real support for resolve_branch_cmd
repos: Introduce commit and branch and alternative to refspec key
repos: Warn if a repo uses legacy refspec
Switch overrides and dump plugin to new commit/branch schema
plugins: for_all_repos: Add support for commit/branch
libkas: Update help test to commit/branch
docs: Update format-changelog
tests: Widely switch to new commit/branch syntax
docs: Update userguide to commit/branch, dropping refspec
tests: Add some test cases to cover handling of legacy refspec

docs/format-changelog.rst | 5 +-
docs/userguide.rst | 41 ++---
image-tests/isar/kas.yml | 6 +-
image-tests/poky/kas.yml | 6 +-
kas/libkas.py | 6 +-
kas/plugins/dump.py | 22 +--
kas/plugins/for_all_repos.py | 14 +-
kas/repos.py | 141 ++++++++++++------
kas/schema-kas.json | 11 +-
tests/test_commands.py | 23 +--
tests/test_commands/test-invalid.yml | 4 +-
tests/test_commands/test.yml | 6 +-
tests/test_environment_variables/test_env.yml | 6 +-
tests/test_layers/test.yml | 10 +-
tests/test_patch.py | 2 +-
tests/test_patch/test-invalid.yml | 4 +-
tests/test_patch/test-invalid2.yml | 4 +-
tests/test_patch/test-invalid3.yml | 4 +-
tests/test_patch/test.yml | 10 +-
tests/test_patch/test2.yml | 10 +-
tests/test_refspec.py | 28 +++-
tests/test_refspec/test.yml | 6 +-
tests/test_refspec/test2.yml | 5 +-
tests/test_refspec/test3.yml | 6 +-
tests/test_refspec/test5.yml | 10 ++
tests/test_refspec/test6.yml | 10 ++
26 files changed, 264 insertions(+), 136 deletions(-)

create mode 100644 tests/test_refspec/test5.yml
create mode 100644 tests/test_refspec/test6.yml

--
2.35.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Covers both the invalid combinations refspec with the new commit/branch
keys as well as the issuing of a warning when a repo contains refspec.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

Changes in v2:
- reset __legacy_refspec_warned__ to fix non-stand-alone execution
- fix copy-and-paste errors of test case folders

tests/test_refspec.py | 28 +++++++++++++++++++++++++++-

tests/test_refspec/test5.yml | 10 ++++++++++
tests/test_refspec/test6.yml | 10 ++++++++++

3 files changed, 47 insertions(+), 1 deletion(-)

create mode 100644 tests/test_refspec/test5.yml
create mode 100644 tests/test_refspec/test6.yml

diff --git a/tests/test_refspec.py b/tests/test_refspec.py

index 6a42aa8..5b3b8d1 100644
--- a/tests/test_refspec.py
+++ b/tests/test_refspec.py
@@ -25,7 +25,7 @@ import pytest
import shutil
from kas import kas
from kas.libkas import run_cmd
-from kas.repos import RepoRefError
+from kas.repos import RepoRefError, Repo


def test_refspec_switch(changedir, tmpdir):
@@ -98,3 +98,29 @@ def test_url_no_refspec(changedir, tmpdir):

os.chdir(tdir)
with pytest.raises(RepoRefError):
kas.kas(['shell', 'test4.yml', '-c', 'true'])
+
+
+def test_commit_refspec_mix(changedir, tmpdir):
+ """
+ Test that mixing legacy refspec with commit/branch raises errors.
+ """

+ tdir = str(tmpdir / 'test_commit_refspec_mix')

+ shutil.copytree('tests/test_refspec', tdir)
+ os.chdir(tdir)
+ with pytest.raises(RepoRefError):
+ kas.kas(['shell', 'test5.yml', '-c', 'true'])
+ with pytest.raises(RepoRefError):
+ kas.kas(['shell', 'test6.yml', '-c', 'true'])
+
+
+def test_refspec_warning(capsys, changedir, tmpdir):
+ """
+ Test that using legacy refspec issues a warning, but only once.
+ """

+ tdir = str(tmpdir / 'test_refspec_warning')

+ shutil.copytree('tests/test_refspec', tdir)
+ os.chdir(tdir)

+ # needs to be reset in case other tests ran before
+ Repo.__legacy_refspec_warned__ = []

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

Covers both the invalid combinations refspec with the new commit/branch
keys as well as the issuing of a warning when a repo contains refspec.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

Changes in v3:
- also fix over-long line

tests/test_refspec.py | 29 ++++++++++++++++++++++++++++-

tests/test_refspec/test5.yml | 10 ++++++++++
tests/test_refspec/test6.yml | 10 ++++++++++

3 files changed, 48 insertions(+), 1 deletion(-)

create mode 100644 tests/test_refspec/test5.yml
create mode 100644 tests/test_refspec/test6.yml

diff --git a/tests/test_refspec.py b/tests/test_refspec.py

index 6a42aa8..c1dfcde 100644

--- a/tests/test_refspec.py
+++ b/tests/test_refspec.py
@@ -25,7 +25,7 @@ import pytest
import shutil
from kas import kas
from kas.libkas import run_cmd
-from kas.repos import RepoRefError
+from kas.repos import RepoRefError, Repo


def test_refspec_switch(changedir, tmpdir):

@@ -98,3 +98,30 @@ def test_url_no_refspec(changedir, tmpdir):

+ 'Using deprecated refspec for repository "kas2".') == 1