eric/ansible-workspace-dnd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete the first suite release

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-17 23:52:46 +00:00
parent 06e1b35f25
commit eda361fa5d
4 changed files with 128 additions and 974 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
docs/roadmap/remediation.md
View File

@@ -1,173 +1,147 @@
# Feature 0012 Remediation Review
# Feature 0013 Remediation Review
Status: resolved
Reviewed implementation commits:
Reviewed implementation and release state:
- `600eb21 Document standalone and collection pipeline usage`
- `3f7f82e Establish the D&D collection foundation`
- `c84aa0d Merge commit '5dbae8a' as 'roles/pipeline'`
- `10ad31c Test the assembled D&D collection`
- Application-role `v0.1.0` tags at the five roadmap-fixed commits
- Pipeline release commit and tag
`7c2bad827702fdcf78f8f77ece7d6270756bc3c5`
- Collection subtree import
`da348eb8bd9878a58404a37dbcf22ad6562ac5c9`
- Collection release commit and tag
`63e8f3fb090a583226c7435bd900e10d41a30b89`
- Public `rakestraw.dnd 0.1.0` Gitea release and
`rakestraw-dnd-0.1.0.tar.gz` attachment
- Workspace implementation record through
`06e1b35f25589a3a6ff3fd2884208c86c4fee9c4`
## Review Summary
Feature 0012 implements the principal target architecture. The standalone
pipeline repository remains authoritative, and collection history records its
exact `600eb21` snapshot as a squashed subtree at `roles/pipeline`. The
collection has valid Galaxy and runtime metadata, exact native collection
dependencies, one unified bootstrap manifest for the five Git-hosted roles,
focused build exclusions, and an isolated artifact-level integration entry
point. The collection builds as `rakestraw.dnd` 0.1.0 and exposes
`rakestraw.dnd.pipeline`.
Feature 0013 implements the release architecture and public consumer path.
The five application-role tags identify the exact reviewed commits selected by
the roadmap. The standalone pipeline and collection manifests use those
immutable tags, and the native collection dependencies remain pinned to
`ansible.posix` 2.2.0 and `community.general` 13.3.0. The collection subtree's
Git tree exactly matches public pipeline tag `v0.1.0`.
Two low-severity issues were found and are now resolved. The collection's
subtree maintenance examples derived a commit from the local sibling
repository but told Git to fetch that commit from a remote which did not
contain it at review time. Separately, the collection integration driver
repeated secret-redaction assertions already owned by the standalone pipeline
suite; those assertions did not validate collection assembly and strengthened
the collection test contract beyond the selected packaging boundary.
All seven repositories and tags are public and synchronized with their local
counterparts. The collection's non-draft, non-prerelease Gitea release carries
one correctly named archive. Its manifest declares `rakestraw.dnd` 0.1.0, the
expected Ansible baseline and collection dependencies, and its file payload
matches a fresh build from the tagged collection tree.
## Finding 1: Subtree Maintenance Commands Mix Local and Remote Sources
One low-severity documentation issue remains. The pipeline README now implies
that collection snapshots may be imported only from role releases. That
strengthens the settled maintenance contract beyond the requested release
feature and contradicts the documented development workflow, which also
permits a reviewed, pushed commit.
## Finding 1: Pipeline Documentation Narrows Subtree Imports to Releases
Severity: low
`ansible-collection-dnd/README.md:51-63` obtains `pipeline_commit` from
`../ansible-role-dnd-pipeline`, but passes the Gitea URL as the repository
argument to both `git subtree add` and `git subtree pull`. The reviewed
pipeline commit was seven commits ahead of `origin/main` at review time; the
remote advertised `b15fe8d`, not imported commit `600eb21`. The documented
command therefore could not reproduce the current import.
`ansible-role-dnd-pipeline/README.md:51-53` says that collection maintainers
“import a reviewed release as a snapshot.” The same sentence is present in the
faithfully imported collection copy at
`ansible-collection-dnd/roles/pipeline/README.md:51-53`.
The collection artifact already contains the imported role, so consumers do
not run these commands or need a sibling checkout. The commands are the
maintainer-facing assembly interface and should also be portable outside this
workspace. The durable contract should therefore use Gitea exclusively: first
push the reviewed pipeline commit or tag to the authoritative repository, then
identify that remote revision explicitly and import it from the same URL.
That wording accurately describes the particular snapshot used for collection
release 0.1.0, but it reads as the general maintenance rule. The durable
architecture deliberately permits the collection to import any reviewed
pipeline commit that has been pushed to Gitea during development. An immutable
pipeline tag is required only when preparing a released compatibility set.
The collection's own maintenance section correctly accepts a pushed commit or
immutable tag.
This is an inadvertent requirement strengthening: it could force an otherwise
unnecessary pipeline-role release merely to assemble and test a development
collection snapshot. It does not affect runtime behavior, the released
dependency pins, subtree fidelity, or consumer installation.
### Required Remediation
- Remove the sibling-repository `git rev-parse` commands from both subtree
examples.
- Define an explicit `pipeline_revision` placeholder representing a reviewed
commit or immutable tag that has already been pushed to Gitea, and pass that
revision with the authoritative Gitea URL to both `git subtree add` and
`git subtree pull`.
- State concisely that a pipeline revision must be committed, reviewed, and
pushed to the authoritative repository before collection assembly imports
it. Do not prescribe a branch name or require a release tag during active
development; a pushed full commit ID remains valid.
- Do not add a configured remote, sibling-path assumption, synchronization
script, lock file, or private provenance state.
- Do not rewrite subtree history or reimport the current role. This is a
collection-owned documentation correction only.
- Confirm that Gitea contains the selected pipeline revision, then validate
the corrected initial command in a disposable Git repository without using
the local sibling repository as the subtree source.
- In the authoritative pipeline README, replace the release-only wording with
concise language saying that collection maintainers import a reviewed,
pushed commit or immutable tag as a snapshot.
- Make no role, manifest, default, task, template, handler, or test change.
- Commit and push the pipeline documentation correction before importing it
into the collection.
- Refresh `roles/pipeline` through the documented squashed subtree command
using the pushed pipeline documentation commit as the remote revision. Do
not edit the collection's subtree copy directly.
- Confirm that the resulting collection subtree Git tree exactly matches the
selected pushed pipeline commit outside Git metadata.
- Do not move or replace any `v0.1.0` tag, modify the published Gitea release,
or replace its attachment. Those immutable artifacts correctly describe the
historical 0.1.0 source state.
- Do not create a new role or collection release solely for this
maintainer-facing wording correction.
## Finding 2: The Collection Test Duplicates Secret-Redaction Coverage
### Required Validation
Severity: low
`ansible-collection-dnd/tests/integration:19-20` defines two synthetic values
solely so lines 74-75 can search the first convergence log for them. Secret-safe
task output is pipeline behavior established by Feature 0011 and already
covered by `ansible-role-dnd-pipeline/tests/integration`. The collection owns
artifact construction, bootstrap installation, FQCN resolution, representative
assembled behavior, and clean repeated convergence; it does not own a second
credential-redaction contract.
The implementation plan required synthetic credentials so native
configuration could be exercised without real provider values, but it did not
require the collection to retest Feature 0011 redaction. These two assertions
are therefore an inadvertent strengthening by the implementing agent and
conflict with the roadmap's instruction to keep detailed pipeline feature
coverage in the standalone role.
The native Seriatim, Audita, Notarius, Scriptorium, and Narratio checks are not
part of this finding. They are state-based, inexpensive, and implement the
roadmap's express requirement for representative native validation of the
assembled suite.
### Required Remediation
- Retain distinctive synthetic credential contents in the collection
convergence variables; no real credential or live provider call may enter
the suite.
- Remove the two shell variables used only for log searching and remove the two
secret-content grep assertions.
- Retain isolated dependency installation, archive boundary checks, FQCN
syntax and lint validation, the selected native application checks, and the
immediate `changed=0 failed=0` repeat.
- Do not replace the removed assertions with another collection-level
credential, log, file-content, or implementation-trace test.
## Resolution
Resolved in collection commits `556b6ed` and `da67b34`.
The collection README now uses an explicit `PUSHED_COMMIT_OR_TAG` revision and
the authoritative Gitea URL for both initial and subsequent subtree imports.
It states that the selected revision must be committed, reviewed, and pushed
before collection assembly. The examples no longer inspect or depend on a
sibling checkout. A disposable repository successfully imported the exact
commit advertised by Gitea through the documented remote-only command shape.
The collection integration driver retains its distinctive synthetic
credential inputs but no longer defines separate values solely for log
searching or duplicates the standalone pipeline suite's two redaction
assertions. Its artifact, dependency, FQCN, native application, and clean
repeat coverage remain unchanged.
## Required Validation
After remediation, run:
Run:
```text
cd ansible-collection-dnd
bash -n tests/integration
tests/integration
cd ansible-role-dnd-pipeline
git diff --check
cd ../ansible-collection-dnd
../.venv/bin/ansible-galaxy collection build --output-path "$(mktemp -d)"
git diff --check
```
The result must demonstrate isolated dependency bootstrap, collection build
and artifact installation, FQCN resolution, the retained native application
checks, and immediate clean convergence. The built artifact must still include
`roles/pipeline/tasks/main.yml` and exclude the selected development-only
subtree content.
Also compare the imported `roles/pipeline` tree with a disposable clone of the
selected pushed pipeline commit. The full application, pipeline, and
collection integration suites do not need to be rerun because the remediation
changes documentation only and preserves all Ansible and dependency content.
Validate the corrected subtree example against Gitea in a disposable Git
repository without modifying the real collection history or relying on the
local sibling repository as the source. The standalone pipeline integration
suite does not need to be rerun for these collection-only documentation and
test-scope changes.
## Resolution
Resolved in pipeline commit `78afffe` and collection subtree import
`5e695f3`.
The authoritative pipeline README now states that collection maintainers may
import either a reviewed, pushed commit or an immutable tag. The pipeline
commit was pushed before the collection imported that exact Gitea revision
through the documented squashed subtree workflow. The imported subtree and
pipeline source have the same Git tree ID,
`37f619ac24d2303847c4b9ea60db1f9fc1bf9d0e`.
A fresh collection build succeeded, and `git diff --check` passed in both
repositories. No Ansible content or dependency selection changed, so the
integration suites were not rerun. The seven `v0.1.0` tags, published
collection release, and release attachment remain unchanged.
## Review Validation Evidence
The review compared the complete standalone pipeline repository with
`roles/pipeline`; the trees are byte-for-byte identical outside Git metadata.
The root bootstrap manifest's role and collection sections exactly match the
two imported pipeline manifests, and `galaxy.yml` declares the same native
collection versions.
- Every local and remote `v0.1.0` tag resolves to the commit recorded in the
Feature 0013 roadmap and implementation notes.
- All seven Gitea repositories report public visibility and `main` as their
default branch.
- The pipeline `v0.1.0` tree ID and the collection tag's
`roles/pipeline` tree ID are both
`44a9d2b010012d8a63720b3a4ed07e9f255a5dae`.
- The tagged raw collection manifest matches the repository manifest, and its
role and collection selections match the released pipeline manifests.
- The public release API reports tag `v0.1.0`, title
`rakestraw.dnd 0.1.0`, `draft: false`, `prerelease: false`, and one
`rakestraw-dnd-0.1.0.tar.gz` attachment.
- The published archive has the same file list, `MANIFEST.json`, `FILES.json`,
and file payload hashes as a fresh collection build from the tagged tree.
It contains the pipeline entry point and omits the selected development-only
subtree files.
- A fresh unauthenticated clone and release-attachment download installed the
five public role tags and the collection into isolated Ansible paths. The
installed `rakestraw.dnd.pipeline` role converged successfully and its
immediate repeat reported `changed=0` and `failed=0`.
- The complete repository-local collection integration suite independently
passed isolated bootstrap, collection build and installation, syntax check,
production-profile lint, native application validation, and immediate clean
convergence.
- `git diff --check` passes for the pipeline, collection, and workspace
implementation ranges. All workspace repositories are clean and synchronized
with their upstream branches before this review finding is recorded.
A fresh collection build produced
`rakestraw-dnd-0.1.0.tar.gz`. The archive contains the pipeline task entry
point and omits the selected nested tests, Ansible configuration, dependency
manifests, and Git ignore file. Installing that artifact into a temporary
collection path made `rakestraw.dnd.pipeline` discoverable. A separate
isolated bootstrap installed the unified requirements, after which syntax
checking and production-profile ansible-lint passed.
`bash -n ansible-collection-dnd/tests/integration`, manifest consistency
checks, `git diff --check`, and collection repository integrity checks also
passed during review.
After remediation, the remote-only subtree command successfully imported the
revision advertised by Gitea into a disposable repository, and a fresh
collection build succeeded. The complete collection integration entry point
then passed isolated dependency installation, artifact construction and
installation, syntax checking, production-profile lint, all retained native
application checks, and two recaps with `changed=0` and `failed=0`. The
standalone pipeline suite was not rerun because neither remediation changed
the authoritative pipeline role.
No runtime code-quality issue, release-architecture gap, test-policy violation,
or other inadvertent requirement strengthening was found.