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

Align the Notarius roadmap with testing policy

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-09 13:59:42 +00:00
parent 3f20cf4b18
commit 77dcf8f7f7
1 changed files with 69 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
docs/roadmap/features/0003-notarius-source-installation-and-configuration.md
View File

@@ -12,16 +12,25 @@ role.
## Problem or Opportunity ## Problem or Opportunity
The `ansible-role-notarius` repository currently contains only its initial At feature selection, the `ansible-role-notarius` repository contained only
placeholder files. Notarius is one of the five required pipeline applications its initial placeholder files. Notarius is one of the five required pipeline
and needs an independently usable installation and native-configuration role applications and needed an independently usable installation and
before the suite role can compose it with Seriatim, Audita, and the remaining native-configuration role before the suite role could compose it with
applications. Seriatim, Audita, and the remaining applications.
Seriatim and Audita have established the preferred source-build architecture. Seriatim and Audita have established the preferred source-build architecture.
Notarius can use the same concise task flow, with only its native configuration Notarius can use the same concise task flow, with only its native configuration
and build contract differing. and build contract differing.
## Governing Policies
- [The Ansible house style](../../ansible.md) governs the role implementation,
its public configuration variables, and its template behavior.
- [The testing house style](../../testing.md) governs repository-local
validation. Tests exercise role-owned behavior through the public interface
without snapshotting current defaults, tracing task implementation, or
rechecking postconditions owned by trusted Ansible modules.
## Scope ## Scope
- Implement `ansible-role-notarius` as a conventional standalone role. - Implement `ansible-role-notarius` as a conventional standalone role.
@@ -91,9 +100,16 @@ final value with ordinary Ansible/Jinja expressions.
An immediate second application reports no changes. A changed Git checkout or An immediate second application reports no changes. A changed Git checkout or
missing binary causes one build; configuration changes converge independently missing binary causes one build; configuration changes converge independently
through the ordinary `ansible.builtin.template` operation. Repository-local through the ordinary `ansible.builtin.template` operation.
tests select immutable `v0.5.0` explicitly before checking its native CLI
output, and validate the managed configuration. Repository-local tests exercise the real role through its public variables.
They use the default invocation only as a smoke test, explicitly select
immutable `v0.5.0` to prove version selection, exercise missing-binary recovery
with a caller-supplied Go executable, and render one representative
configuration covering null omission, intentional falsey values, and
caller-side pipeline composition. Application-native commands verify the
selected release and configuration validity, and immediate repeated
applications verify convergence.
## Repository Ownership ## Repository Ownership
@@ -271,53 +287,58 @@ its configuration.
## Acceptance Criteria ## Acceptance Criteria
- Unsupported distributions, Ubuntu releases, and architectures fail before ### Required Role Behavior
application state is modified.
- Default execution on the local Ubuntu 26.04 host installs or confirms Git - The role rejects unsupported distributions, Ubuntu releases, and
and Go and checks out tag `v0.6.0` at commit architectures before modifying application state.
- On a supported host, the role installs the selected Notarius source release
with its upstream build contract. The default selection for this feature is
tag `v0.6.0`, resolving to commit
`77ae132e5609916da40dcd4fcc749c000a63cbac`. `77ae132e5609916da40dcd4fcc749c000a63cbac`.
- The role builds with the fixed upstream contract and installs - The role converges the source tree, binary, and configuration to the paths,
`/usr/local/bin/notarius` as a regular file owned by `root:root` with mode ownership, and modes defined above using the responsible Ansible modules.
`0755`. - The default template renders the minimal valid configuration containing the
- The managed source checkout is recursively owned by `root:root`. required schema version and leaves optional policy to Notarius.
- The default configuration contains exactly `version: 4` and is installed at - A non-null optional variable renders its corresponding native field. Null
`/usr/local/etc/notarius/config.yml`, owned by `root:root` with mode `0644`. values and parent sections without a selected descendant are omitted;
- Every optional field is absent when its variable is null, including parent intentional falsey values are preserved.
sections with no selected descendants.
- A representative configuration exercises every top-level section and
validates successfully with `notarius config validate`.
- Explicit falsey non-null values, including zero and false, are rendered
rather than omitted; semantic validity remains Notarius's responsibility.
- Repository-local tests explicitly select `v0.5.0`, receive `notarius v0.5.0`
from the installed CLI, and successfully validate the managed configuration.
- An immediate second role run reports no changes.
- A missing binary causes one rebuild followed by an unchanged run.
- A changed checkout causes one rebuild followed by an unchanged run.
- A configuration change updates only configuration state and does not rebuild
the binary.
- Dependency opt-out accepts a caller-supplied `notarius_go_binary`.
- A play connecting as an ordinary sudo-capable user can apply the role without
play-level privilege escalation.
- Defaults and argument specifications contain exactly the eight installation
variables and fourteen configuration variables in the Fixed Public
Interface.
- No raw `notarius_config` compatibility variable, template override, or
parallel configuration interface exists.
- Independently defined inventory mappings can be combined into - Independently defined inventory mappings can be combined into
`notarius_pipelines`, and the resulting pipeline IDs and definitions are `notarius_pipelines`, and the resulting pipeline IDs and definitions are
rendered without structural rewriting by the role. rendered without structural rewriting by the role.
- Production tasks contain no CLI validation, fingerprints, checksums, sidecar - A changed checkout or missing binary causes the imperative build to run. An
state, manual Git reset or clean commands, or probes before state already immediate repeated application with unchanged inputs reports no changes.
managed by APT, Snap, `file`, `git`, or `template`. - Dependency opt-out accepts a caller-supplied `notarius_go_binary`.
- Syntax checking, production-profile ansible-lint, focused local convergence, - Tasks requiring elevated access use task-level privilege escalation, so the
CLI verification, configuration validation, and clean repeated runs pass. role does not require play-level escalation.
- Role documentation describes actual behavior, dependency opt-out, every - Defaults, argument specifications, template behavior, and documentation
public configuration variable, null-as-omission behavior, the native remain aligned with the public interface without introducing a parallel raw
`pipelines` boundary and caller-side composition example, privilege use, and configuration or template-override interface.
integration-test effects. - Production tasks contain no role-private build state, redundant probes,
application self-tests, or other behavior outside the selected invariants.
- No repository other than `ansible-role-notarius` and the workspace control - No repository other than `ansible-role-notarius` and the workspace control
repository is modified. repository is modified.
### Required Validation
- Syntax checking and production-profile ansible-lint pass.
- A default invocation provides a smoke test through the installed CLI and
native configuration validator, followed immediately by a role application
reporting no changes. The test does not assert that the role's current
default release or complete default document remains unchanged.
- A focused version-selection case explicitly requests immutable tag `v0.5.0`
and verifies that the installed CLI reports `notarius v0.5.0`.
- One recovery case removes the binary, disables dependency management,
supplies a caller-selected Go executable, confirms that executable is used,
and finishes with a clean repeated application.
- One representative configuration case verifies selected rendered values,
selected omissions, intentional falsey values, and caller-side composition
of two pipeline mappings. The native Notarius validator accepts the result,
and an immediate repeated application reports no changes.
- Tests do not assert task names or order, individual task results, exact
current defaults, complete configuration snapshots, public-variable counts,
trusted-module file or package postconditions, or an exhaustive negative
platform matrix.
## Dependencies and Follow-up Work ## Dependencies and Follow-up Work
The managed host requires access to the Notarius Git repository, Ubuntu Snap The managed host requires access to the Notarius Git repository, Ubuntu Snap