Plan the first coordinated suite release
This commit is contained in:
285
docs/roadmap/features/0013-first-coordinated-suite-release.md
Normal file
285
docs/roadmap/features/0013-first-coordinated-suite-release.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# Feature 0013: Publish the First Coordinated Suite Release
|
||||
|
||||
Status: ready
|
||||
|
||||
## Summary
|
||||
|
||||
Publish the reviewed D&D pipeline as the first immutable, remotely installable
|
||||
release of its five application roles, standalone pipeline role, and
|
||||
`rakestraw.dnd` collection. The release establishes `v0.1.0` tags in the
|
||||
projects' public Gitea repositories, replaces development commit pins with
|
||||
those role tags, and makes the built `rakestraw-dnd-0.1.0.tar.gz` collection
|
||||
artifact available from the collection's Gitea release.
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
The application roles, pipeline role, and collection have been implemented,
|
||||
reviewed, and tested as one compatible suite. Their current dependency
|
||||
manifests still select application roles by development commit, however, and
|
||||
none of the seven Ansible repositories has an immutable release tag. The
|
||||
collection documentation consequently describes a development build rather
|
||||
than a published release, and a consumer cannot bootstrap the reviewed suite
|
||||
entirely from named releases and a published collection artifact.
|
||||
|
||||
The initial release should turn the existing reviewed compatibility set into a
|
||||
durable public installation boundary without changing application behavior or
|
||||
introducing release automation. It must prove that the release is consumable
|
||||
from Gitea alone rather than from sibling repositories or unpublished local
|
||||
artifacts.
|
||||
|
||||
## Governing Policies
|
||||
|
||||
- [The Ansible house style](../../ansible.md) governs dependency manifests,
|
||||
collection packaging, and concise consumer documentation.
|
||||
- [The testing house style](../../testing.md) governs release validation. The
|
||||
feature reuses behavior-oriented repository suites and adds only validation
|
||||
specific to the remote publication boundary.
|
||||
- [The planning policy](../../planning.md) governs the cross-repository
|
||||
implementation and review workflow.
|
||||
- [The MVP roadmap](../mvp.md) defines independent role releases, immutable
|
||||
release pins, the collection as the compatibility record, and public Gitea
|
||||
as the release source.
|
||||
- [Feature 0012](0012-collection-assembly.md) defines the authoritative
|
||||
pipeline subtree, unified consumer manifest, and assembled-artifact testing
|
||||
boundary that this feature releases without redesigning.
|
||||
|
||||
## Scope
|
||||
|
||||
- Publish `v0.1.0` as the initial release of each standalone application role:
|
||||
`rakestraw.audita`, `rakestraw.narratio`, `rakestraw.notarius`,
|
||||
`rakestraw.seriatim`, and `rakestraw.scriptorium`.
|
||||
- Point those application-role tags at the exact reviewed commits already
|
||||
selected by the pipeline compatibility manifest. No application-role code
|
||||
or default changes are part of release preparation.
|
||||
- Replace the five development commit pins in the authoritative pipeline
|
||||
role's root dependency manifest with the corresponding immutable `v0.1.0`
|
||||
role tags.
|
||||
- Update the pipeline documentation to describe the released dependency pins
|
||||
and its standalone installation path without changing its role interface or
|
||||
runtime behavior.
|
||||
- Validate and publish `v0.1.0` of the standalone pipeline role after its
|
||||
release manifest and documentation are complete.
|
||||
- Import the published pipeline `v0.1.0` state into the collection's
|
||||
`roles/pipeline` subtree using the established remote-only, squashed subtree
|
||||
workflow.
|
||||
- Replace the collection's five application-role commit pins with the same
|
||||
`v0.1.0` tags used by the authoritative pipeline role, retaining the exact
|
||||
`ansible.posix` and `community.general` version pins already selected.
|
||||
- Retain collection version `0.1.0` in `galaxy.yml`, update collection
|
||||
documentation from development-build language to released installation
|
||||
instructions, and identify the release as the compatibility record for the
|
||||
seven selected component versions.
|
||||
- Create and push public, immutable `v0.1.0` tags for all seven Ansible
|
||||
repositories.
|
||||
- Build `rakestraw-dnd-0.1.0.tar.gz` from the tagged collection content and
|
||||
create a concise public Gitea `v0.1.0` collection release whose attachment
|
||||
is that exact artifact.
|
||||
- Validate that a clean consumer can obtain the tag-pinned dependency manifest
|
||||
and collection archive from their public Gitea URLs, install them into
|
||||
isolated Ansible paths, invoke `rakestraw.dnd.pipeline`, and obtain an
|
||||
immediate clean repeat.
|
||||
- Record the completed release and its immutable compatibility set in the
|
||||
workspace status and durable release-facing documentation.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Changing application versions, role defaults, pipeline configuration,
|
||||
filesystem policy, credentials, assets, or deployed runtime behavior.
|
||||
- Synchronizing future versions of independently released roles. The shared
|
||||
initial version is a convenient baseline, not a lockstep release policy.
|
||||
- Publishing the collection to Ansible Galaxy, Automation Hub, or another
|
||||
package registry.
|
||||
- Vendoring the five application roles into the collection or changing the
|
||||
selected pipeline subtree model.
|
||||
- Adding CI/CD, a release script, a changelog generator, dependency-update
|
||||
automation, or a general-purpose release framework.
|
||||
- Adding tests that snapshot manifest text, tag names, defaults, task traces,
|
||||
or other implementation details. Release validation should exercise the
|
||||
public installation and deployed behavior.
|
||||
- Signing tags or artifacts, generating checksums or software bills of
|
||||
materials, mirroring dependencies, or adding other supply-chain hardening.
|
||||
- Defining upgrade, downgrade, removal, scheduling, or optional human-operator
|
||||
account management.
|
||||
|
||||
## Target End State
|
||||
|
||||
Each public application-role repository has an immutable `v0.1.0` tag for the
|
||||
exact role revision already reviewed as part of the assembled suite:
|
||||
|
||||
| Role | Released revision |
|
||||
| --- | --- |
|
||||
| `rakestraw.audita` | `66ebea9a47ce82bfdbdc5e2855f3dfaaff8e2a16` |
|
||||
| `rakestraw.narratio` | `292d8669e7aad5cfe80b0c469d22b6177e8cf0f1` |
|
||||
| `rakestraw.notarius` | `14a38e04e35ef524d6a97fa7fb5a04981a0a2161` |
|
||||
| `rakestraw.seriatim` | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` |
|
||||
| `rakestraw.scriptorium` | `8b4c86e48e7d8655e479b26dc510bf01683a0c8f` |
|
||||
|
||||
The standalone pipeline role has its own immutable public `v0.1.0` tag. Its
|
||||
role dependency manifest selects all five application roles with
|
||||
`version: v0.1.0`, and its collection dependency manifest retains
|
||||
`ansible.posix` 2.2.0 and `community.general` 13.3.0. The pipeline release is
|
||||
independently installable under `rakestraw.dnd_pipeline`.
|
||||
|
||||
The collection's `roles/pipeline` subtree is a faithful squashed import of the
|
||||
published pipeline `v0.1.0` release. Its consumer-facing `requirements.yml`
|
||||
contains the same five role tags and collection versions as the standalone
|
||||
pipeline manifests. `galaxy.yml` remains version `0.1.0`, and the collection
|
||||
repository has an immutable `v0.1.0` tag and corresponding public Gitea
|
||||
release to carry the built artifact.
|
||||
|
||||
The collection release includes the archive produced from that released tree,
|
||||
named `rakestraw-dnd-0.1.0.tar.gz`. Its public release notes identify the exact
|
||||
five application-role versions, pipeline-role version, native collection
|
||||
dependencies, supported platform, and consumer bootstrap steps. A consumer
|
||||
can fetch the tagged manifest and archive through public Gitea URLs and
|
||||
install the suite without access to this development workspace.
|
||||
|
||||
## Repository Ownership
|
||||
|
||||
- The five standalone application-role repositories own their respective
|
||||
`v0.1.0` tags. Their reviewed role content remains unchanged by this
|
||||
feature.
|
||||
- `ansible-role-dnd-pipeline` owns its tag-pinned role manifest, standalone
|
||||
release documentation, and `v0.1.0` tag.
|
||||
- `ansible-collection-dnd` owns the released pipeline subtree, unified
|
||||
tag-pinned consumer manifest, collection release documentation, collection
|
||||
tag, built artifact, and Gitea release attachment.
|
||||
- `ansible-workspace-dnd` owns this roadmap, cross-repository compatibility
|
||||
record, active implementation plan, progress tracking, and independent
|
||||
release review.
|
||||
- The application source repositories, campaign repository, prompt-library
|
||||
repository, and `rakestraw-ansible` are unchanged release inputs.
|
||||
|
||||
## Constraints and Settled Decisions
|
||||
|
||||
- Public repositories beneath
|
||||
`https://gitea.maximumdirect.net/eric/` are the authoritative publication
|
||||
channel for this release.
|
||||
- Every Ansible repository uses initial release tag `v0.1.0`. The collection's
|
||||
Galaxy version remains the corresponding unprefixed `0.1.0`, as required by
|
||||
collection metadata and artifact naming.
|
||||
- Tags are immutable release boundaries. A release candidate must be validated
|
||||
before its tag is created and pushed; published tags must not be moved to
|
||||
repair a failed release.
|
||||
- The five application-role tags identify the exact reviewed commits shown in
|
||||
the target end state. Release metadata must not create otherwise unnecessary
|
||||
commits in those repositories.
|
||||
- Released role dependency manifests use tag names, not branches or commit
|
||||
hashes. Application repositories remain independently versioned after this
|
||||
shared initial baseline.
|
||||
- The pipeline repository remains authoritative. Its release must be pushed
|
||||
to Gitea before the collection imports the `v0.1.0` revision through the
|
||||
documented remote-only subtree command.
|
||||
- The collection tag identifies the exact source tree from which the attached
|
||||
artifact is built. The attached file must not be rebuilt from a later or
|
||||
dirty tree while retaining the same version.
|
||||
- The public collection release attachment is the selected binary publication
|
||||
interface. The repository tag remains the source publication interface.
|
||||
- Consumer validation must not use sibling checkouts, normal user Ansible
|
||||
paths, preinstalled project roles, or an unpublished local collection
|
||||
archive.
|
||||
- The collection's Gitea release description and existing repository
|
||||
documentation are
|
||||
sufficient for the initial release. This feature does not introduce
|
||||
repository-local changelog files solely to duplicate those notes.
|
||||
|
||||
## Simplest Viable Implementation
|
||||
|
||||
Use ordinary Git tags, one collection Gitea release, existing Ansible
|
||||
dependency manifests, the established subtree command, and `ansible-galaxy
|
||||
collection build`. The five application roles need validation and tags only.
|
||||
The pipeline and collection need small manifest and documentation changes
|
||||
before their respective release tags are created.
|
||||
|
||||
Reuse the existing repository-local integration entry points as release gates.
|
||||
The collection integration suite already exercises isolated dependency
|
||||
bootstrap, archive construction and installation, FQCN resolution, native
|
||||
application behavior, and clean repeated convergence. Adapt its inputs only as
|
||||
necessary to consume the release tags, and use a focused final smoke path to
|
||||
download the published manifest and attached archive from Gitea. Do not add a
|
||||
second release framework or duplicate the detailed behavior matrices owned by
|
||||
the standalone repositories.
|
||||
|
||||
Publication is intentionally manual for the first release. The work does not
|
||||
yet justify release scripts, workflow files, persistent staging state, or a
|
||||
new packaging service.
|
||||
|
||||
## Rationale and Alternatives
|
||||
|
||||
Immutable role tags give consumers meaningful versions while preserving the
|
||||
settled model of independently released repositories. Publishing only commit
|
||||
hashes would be reproducible but would not establish the named release
|
||||
contract required by the MVP. Publishing branches would not be immutable.
|
||||
|
||||
Using `v0.1.0` for every initial role and the collection makes the first
|
||||
compatibility baseline easy to understand. Future role releases remain
|
||||
independent, and future collection releases record whatever combination is
|
||||
then supported; no synchronized-version policy is implied.
|
||||
|
||||
Attaching the Galaxy-built archive to the public Gitea collection release
|
||||
provides a direct installation artifact without introducing another registry.
|
||||
Requiring consumers to clone and build the collection would expose unnecessary
|
||||
development steps, while publishing to Ansible Galaxy or Automation Hub would
|
||||
add an unselected distribution channel and account lifecycle.
|
||||
|
||||
Manual publication is appropriate for one initial release and keeps the
|
||||
release contract visible. Automation can be considered after repeated release
|
||||
work demonstrates a stable process worth encoding.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Each application-role repository advertises a public, immutable `v0.1.0`
|
||||
tag at the exact reviewed revision listed in this roadmap.
|
||||
- Each application role's existing syntax, lint, integration, and clean-repeat
|
||||
validation passes for the candidate being tagged; no role behavior is
|
||||
changed merely to create the release.
|
||||
- The pipeline role's released manifest selects all five application roles by
|
||||
`v0.1.0`, and its collection dependency versions remain unchanged.
|
||||
- The pipeline's existing validation installs its application-role
|
||||
dependencies from the public Gitea tags, exercises the role through its
|
||||
public interface, and passes its immediate clean repeat.
|
||||
- The pipeline repository advertises a public, immutable `v0.1.0` tag at the
|
||||
validated release commit.
|
||||
- The collection subtree matches the published pipeline `v0.1.0` tree outside
|
||||
repository-specific Git metadata and records the remote Gitea import in Git
|
||||
history.
|
||||
- The collection's root manifest uses the same five `v0.1.0` application-role
|
||||
pins and exact native collection versions as the released pipeline role.
|
||||
- `ansible-galaxy collection build` from the collection release candidate
|
||||
produces `rakestraw-dnd-0.1.0.tar.gz`, and the existing artifact-boundary
|
||||
exclusions remain effective.
|
||||
- The collection's existing integration suite passes against the release
|
||||
candidate, including isolated bootstrap, installed-artifact FQCN use,
|
||||
representative native application checks, and immediate `changed=0` and
|
||||
`failed=0` convergence.
|
||||
- The collection repository advertises a public, immutable `v0.1.0` tag and
|
||||
matching Gitea release. The archive attached to that release is the artifact
|
||||
built from the tagged tree.
|
||||
- A clean remote-only smoke validation downloads the public tag-pinned
|
||||
manifest and public collection attachment, installs into isolated paths,
|
||||
resolves `rakestraw.dnd.pipeline`, and completes with a clean immediate
|
||||
repeat without referencing any sibling repository or unpublished artifact.
|
||||
- Release-facing documentation no longer describes collection `0.1.0` or the
|
||||
role release tags as future or unpublished, and it gives the complete public
|
||||
Gitea installation path without requiring the development workspace.
|
||||
- All participating repositories are clean, their release commits and tags
|
||||
are present upstream, and workspace status records the published
|
||||
compatibility baseline.
|
||||
|
||||
## Dependencies and Follow-up Work
|
||||
|
||||
Feature 0012 and its remediation must remain complete. Credentials capable of
|
||||
pushing commits and tags and creating the public collection Gitea release and
|
||||
attachment must be available during implementation.
|
||||
|
||||
Potential later features include release automation, publication to an Ansible
|
||||
registry, independently versioned follow-up releases, optional suite-level
|
||||
operator membership management, and defined upgrade, downgrade, or removal
|
||||
behavior. None is required for the initial release.
|
||||
|
||||
## Potential Future Hardening
|
||||
|
||||
- Signed Git tags or release artifacts.
|
||||
- Published checksums, provenance attestations, or software bills of
|
||||
materials.
|
||||
- Automated verification and publication in a controlled CI environment.
|
||||
Reference in New Issue
Block a user