Correct forward-pointer entries in retirement guide - #1047
Draft
ideaship wants to merge 2 commits into
Draft
Conversation
❌MegaLinter analysis: Error
Detailed Issues❌ MARKDOWN / markdown-table-formatter - 1 error❌ MARKDOWN / markdownlint - 8 errors
|
ideaship
force-pushed
the
docs/fix-forward-pointer-entries
branch
from
August 4, 2026 12:03
d1f4849 to
15f4fc2
Compare
Four of the seven entries under "Version pointers that move forward (not retirement)" no longer matched the repositories they describe, and the section gave the reader no way to tell its own two cases apart. Checked each entry against the current sources. - testbed does not keep version defaults in config/scripts/*.sh; that path does not exist. What governs is openstack_version / openstack_version_next in .zuul.yaml, backed by the | default(...) values in playbooks/*.yml. terraform/ and scripts/ do carry their own version defaults, but the playbook passes VERSION_OPENSTACK to make, make writes openstack_version into the generated tfvars on both branches of its conditional, and every caller of the upgrade scripts passes all four arguments -- so those inner defaults are shadowed on every automated path and are not pointers to advance. Say so, rather than listing them as if editing them had an effect. - The per-component origin/stable/<version> map in the release repository's src/git-diff-log.py is pinned at 2023.1 throughout and has not been advanced with the releases, so it is not in fact maintained as a forward pointer. Note that it needs checking before it is treated as one; whether the script is still used was not established here. - The defaults entry named one conditional as though it were the only one. all/002-images-kolla.yml gates image selection in more than one place and all/099-kolla.yml gates enablement and other settings the same way. All of them enumerate a set of versions, so none is a pointer that advances; point at the retirement section instead of describing them as pointers that happen to belong elsewhere. - openstackclient_version in ansible-collection-services is derived from openstack_version rather than pinned, so there is nothing to advance. Keep the entry, since the point of the section is to list what must not be mistaken for a retirement target, but state that it is derived. The openstack-ironic-images, zuul-jobs and container-images entries were checked and are accurate as written. Two rules of thumb are added ahead of the list, because four wrong entries out of seven is a sign the reader needs a test rather than a longer list: whether the reference names one version or a set, and which layer actually supplies the value. Both are stated as rules and not as an inventory of current values, so they do not need re-auditing every release -- ansible-collection-services is cited as the shape to aim for, since a value derived from a single source cannot go stale. Assisted-by: Claude:claude-opus-5 Signed-off-by: Roger Luethi <luethi@osism.tech>
ideaship
force-pushed
the
docs/fix-forward-pointer-entries
branch
2 times, most recently
from
August 4, 2026 13:48
dd0b4bd to
9a6ec3d
Compare
The removal checklist covered each repository's per-version build matrix and nothing else, so it read as complete while leaving behind logic that is also keyed on the release. The testbed row went further and said "verification only", which is wrong: testbed carries a per-version case statement selecting the key-value store service. That gate is not one place. The same case appears in testbed and metalbox as byte-identical copies of a valkey_or_redis() helper, again in container-image-kolla-ansible scripts/test.sh as a hand-written variant setting several variables rather than echoing a name, and once more declaratively in the defaults repository as enable_redis / enable_valkey. There is no shared library, so the copies can only be kept in step by editing each one. Name them in the rows that own them, so following the checklist reaches all of them. defaults gets a row of its own. The forward-pointer section sends the reader here for the version gates in all/002-images-kolla.yml and all/099-kolla.yml, and until now the checklist did not mention the repository at all, so that cross-reference led nowhere. The row also covers all/010-<version>.yml, a backward-compat layer that extends the 001 mirror for an older supported release: its own header says to delete it when that release leaves the range, which makes it a retirement step recorded only in a comment. Since two rows now describe repositories with no build matrix, the sentence introducing the table no longer claims they all have one. Add a note on the pattern rather than only the instance. A gate naming a retired release is dead, not broken: no build fails, so nothing prompts the cleanup, which is how a victoria gate survived years in a defaults image selection. The note therefore frames a retirement as incomplete until nothing names the retired release, and points at the rows as the control. The note deliberately says nothing about which of this a drift check can find. Coverage is a property of the checker at a point in time, so asserting it here would either be wrong on merge or need a follow-up documentation change every time the checker gains or loses a check -- the same reason this series states rules instead of inventorying current values. The checker reports its own findings with their own remediation text; this guide's job is to say which files to edit while doing the work. Assisted-by: Claude:claude-opus-5 Signed-off-by: Roger Luethi <luethi@osism.tech>
ideaship
force-pushed
the
docs/fix-forward-pointer-entries
branch
from
August 4, 2026 14:52
9a6ec3d to
252aee9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Four of the seven entries under "Version pointers that move forward
(not retirement)" no longer matched the repositories they describe, and the
section gave the reader no way to tell its own two cases apart. Two commits:
the entries themselves, then the removal checklist on the other side of the
same distinction.
Correct forward-pointer entries in retirement guideChecked every entry against the current sources.
testbeddoes not keep version defaults inconfig/scripts/*.sh— thatpath does not exist. More importantly, the entry pointed at values that
govern nothing. What governs is
openstack_version/openstack_version_nextin.zuul.yaml, backed by the| default(...)values in
playbooks/*.yml. Everything below that is shadowed: the playbookpasses
VERSION_OPENSTACKtomake,makewritesopenstack_versionintothe generated tfvars on both branches of its conditional (so
terraform/variables.tf's default is unreachable), and every caller of theupgrade scripts passes all four arguments (so their
${3:-…}fallbacks areunreachable too). Anyone following the old entry would have edited inert
literals and left the real pointer untouched.
release— theorigin/stable/<version>map insrc/git-diff-log.pyispinned at
2023.1for every entry and has not advanced with the releases, soit is not in fact maintained as a forward pointer. Say it needs checking
before being treated as one; whether the script is still used was not
established here.
defaults— the entry named one conditional as though it were the onlyone.
all/002-images-kolla.ymlgates image selection in more than one place,and
all/099-kolla.ymlgates enablement and other settings the same way. Allenumerate a set of versions, so none is a pointer that advances.
ansible-collection-services—openstackclient_versionis derived fromopenstack_versionrather than pinned, so there is nothing to advance. Theentry stays, since the section's purpose is to list what must not be mistaken
for a retirement target, but it now says it is derived.
openstack-ironic-images,zuul-jobsandcontainer-imageswere checked andare accurate as written.
Two rules of thumb are added ahead of the list, because four wrong entries
out of seven suggests the reader needs a test rather than a longer list: does the
reference name one version or a set, and which layer actually supplies the
value.
ansible-collection-servicesis cited as the shape to aim for — a valuederived from a single source cannot go stale.
Cover version-keyed logic in the removal checklistThe removal checklist covered each repository's per-version build matrix and
nothing else, so it read as complete while leaving behind logic that is also
keyed on the release. The
testbedrow went further and said "verificationonly", which is wrong.
That gate is not in one place. The same
caseselecting the key-value storeappears in
testbed/scripts/include.shandmetalbox/scripts/include.shasbyte-identical copies of a
valkey_or_redis()helper, again incontainer-image-kolla-ansible/scripts/test.shas a hand-written variant thatsets several variables instead of echoing a name, and once more declaratively in
defaultsasenable_redis/enable_valkey. No shared library, so the copiescan only be kept in step by editing each one — hence naming them in the rows
that own them.
defaultsgets a row of its own. The forward-pointer section sends the readerhere for the gates in
all/002-images-kolla.ymlandall/099-kolla.yml, anduntil now the checklist did not mention the repository at all — so that
cross-reference led nowhere. The row also covers
all/010-<version>.yml, abackward-compat layer extending the 001 mirror for an older supported release:
its own header says to delete it when that release leaves the range, which makes
it a retirement step recorded only in a comment. Two rows now describe
repositories with no build matrix, so the sentence introducing the table no
longer claims they all have one.
A note covers the pattern rather than just this instance: a gate naming a
retired release is dead, not broken, so no build fails to prompt the cleanup —
which is how a
victoriagate survived years in adefaultsimage selection. Aretirement is therefore incomplete until nothing still names the retired release,
and the rows are the control.
The note deliberately says nothing about which of this a drift check can
find, which also makes this PR independent of the drift-checker work. Coverage
is a property of the checker at a point in time: asserting it here would be wrong
on merge in one order, and would need a follow-up docs change every time the
checker gains or loses a check. Same reason this series states rules instead of
inventorying current values. The checker reports its own findings with their own
remediation text; this guide's job is to say which files to edit while doing the
work. So this PR and osism/release#2642 can merge in either order, and no
follow-up docs update is owed when a gate check lands.
Deliberately not included
No inventory of current values. An earlier draft recorded which defaults are
stale and at what version — that rots on the next release and documents defects
instead of fixing them. The rules are stated so they do not need re-auditing.
Nor are any repositories changed here: the stale literals turned out to be
shadowed on every automated path, so there is no live bug to fix, only a
maintainability smell that is out of scope for a docs correction.
Assisted-by: Claude:claude-opus-5
Signed-off-by: Roger Luethi luethi@osism.tech
Stack created with GitHub Stacks CLI • Give Feedback 💬