Plan ReleaseKit adoption and a major-release hard cutover
This commit is contained in:
@@ -57,8 +57,9 @@ known publication blocker to adoption.
|
|||||||
establish what execution needs. Review generic override forwarding explicitly.
|
establish what execution needs. Review generic override forwarding explicitly.
|
||||||
3. Install standard inspection and configuration commands, native formats,
|
3. Install standard inspection and configuration commands, native formats,
|
||||||
help/version, and suite-consistent aliases/completion through supported APIs.
|
help/version, and suite-consistent aliases/completion through supported APIs.
|
||||||
Supply the application's version identity from its selected ReleaseKit
|
Supply the application's version identity from the ReleaseKit v0.9.0
|
||||||
integration. Do not use a broad private CLI framework around CommandKit.
|
integration selected in the master roadmap. Do not use a broad private CLI
|
||||||
|
framework around CommandKit.
|
||||||
4. Adapt domain process handlers to reporting/outcome boundaries, preserving
|
4. Adapt domain process handlers to reporting/outcome boundaries, preserving
|
||||||
transcript/artifact integrity, cancellation, and partial success. Specify quiet
|
transcript/artifact integrity, cancellation, and partial success. Specify quiet
|
||||||
mode, completion summaries, and write failures before implementation. Standard
|
mode, completion summaries, and write failures before implementation. Standard
|
||||||
|
|||||||
@@ -91,21 +91,23 @@ locations and import defaults still need selection before changing operator
|
|||||||
behavior. Preserve explicit-path error evidence and distinguish optional from
|
behavior. Preserve explicit-path error evidence and distinguish optional from
|
||||||
required imports using native semantics.
|
required imports using native semantics.
|
||||||
|
|
||||||
**Alternative:** configure the native API with today's two system locations and
|
**Alternative:** configure the native API with two system locations and imports
|
||||||
imports disabled. This eases installation migration and remains supported, but
|
disabled if deployment requirements justify that source-selection policy. This
|
||||||
should be retained only if deployment requirements justify it; historical behavior
|
limits discovery flexibility and must stand on its own merits; compatibility with
|
||||||
alone does not satisfy the suite-alignment objective. Conversely, enabling all
|
today's installations carries no weight. Conversely, enabling all
|
||||||
possible searches/imports without a selected convention can load unintended
|
possible searches/imports without a selected convention can load unintended
|
||||||
sources and is not required for full API adoption.
|
sources and is not required for full API adoption.
|
||||||
|
|
||||||
### Application Schema Version
|
### Application Schema Version
|
||||||
|
|
||||||
**Recommendation:** retain `version: 2` only if the resulting application fields
|
**Recommendation:** design the application schema around the target ownership
|
||||||
and meaning remain coherent after PromptKit ownership is settled. Do not confuse
|
boundaries, then choose its version to describe that contract. Keeping `version: 2`
|
||||||
it with the library version or PromptKit's source header. This avoids meaningless
|
is reasonable only if its meaning remains coherent; compatibility with existing
|
||||||
schema churn while allowing deliberate field migration.
|
files is not a selection criterion. Do not confuse the application schema version
|
||||||
|
with the library version or PromptKit's source header.
|
||||||
|
|
||||||
**Alternative:** introduce a new application schema version if backend or
|
**Alternative:** introduce a new application schema version if backend or
|
||||||
credential ownership changes make existing files misleading. It provides a clear
|
credential ownership changes make existing files misleading. It provides a clear
|
||||||
migration boundary, at the cost of updating files and guidance. Decide from the
|
migration boundary; the version alone does not explain the new contract, so
|
||||||
final schema, not from dependency version numbers alone.
|
hard-cutover guidance still needs to describe it. Decide from the final schema,
|
||||||
|
not from dependency version numbers alone, and do not add legacy-schema support.
|
||||||
|
|||||||
@@ -7,13 +7,15 @@ no implementation or dependency changes have been made for this adoption.
|
|||||||
|
|
||||||
## Objective and Document Ownership
|
## Objective and Document Ownership
|
||||||
|
|
||||||
Align Audita with the supported happy path of ConfigKit, PromptKit, and
|
Align Audita with the supported happy path of ConfigKit, PromptKit, CommandKit,
|
||||||
CommandKit so operators encounter the same conventions across the application
|
and ReleaseKit so operators and maintainers encounter the same conventions
|
||||||
suite. Existing Audita behavior alone is not a reason to diverge.
|
across the application suite. Choose the best target state for Audita; maintaining
|
||||||
|
compatibility with current behavior carries no weight in this major release.
|
||||||
|
|
||||||
This document owns shared adoption principles, sequencing, dependency selection,
|
This document owns shared adoption principles, sequencing, dependency selection,
|
||||||
and cross-library decisions. The linked outlines own library-specific outcomes,
|
and cross-library decisions, including the ReleaseKit adoption work below. The
|
||||||
work, acceptance criteria, and open decisions:
|
linked outlines own library-specific outcomes, work, acceptance criteria, and
|
||||||
|
open decisions:
|
||||||
|
|
||||||
| Outline | Responsibility |
|
| Outline | Responsibility |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -40,6 +42,17 @@ They do not select unrelated work in [future.md](future.md).
|
|||||||
the full ckprompt inspection command set. The libraries are young; problematic
|
the full ckprompt inspection command set. The libraries are young; problematic
|
||||||
or incomplete behavior is a candidate for an upstream change request rather
|
or incomplete behavior is a candidate for an upstream change request rather
|
||||||
than a permanent Audita workaround.
|
than a permanent Audita workaround.
|
||||||
|
- **ReleaseKit:** adopt `go.maximumdirect.net/releasekit` v0.9.0 and move as much
|
||||||
|
release machinery upstream as possible. Audita may select any number of
|
||||||
|
ReleaseKit-owned validators. Retain local release validation only with a
|
||||||
|
documented domain-specific justification. Treat its maturity as broadly
|
||||||
|
similar to PromptKit, though somewhat lower; significant gaps are candidates
|
||||||
|
for focused upstream requests.
|
||||||
|
- **Major-release cutover:** old configuration, CLI, output, and release-workflow
|
||||||
|
behavior impose no compatibility requirement. Do not add compatibility aliases,
|
||||||
|
dual formats, transition modes, or legacy-behavior tests merely to ease adoption.
|
||||||
|
Release guidance may require a hard cutover. Domain requirements still guide
|
||||||
|
the target, but existing implementations and contracts are open to redesign.
|
||||||
- Audita continues to own transcript formats, correction ordering, domain
|
- Audita continues to own transcript formats, correction ordering, domain
|
||||||
validation, structured-response contracts, and truthful partial-success
|
validation, structured-response contracts, and truthful partial-success
|
||||||
behavior. Inspect each other restriction against a concrete domain need.
|
behavior. Inspect each other restriction against a concrete domain need.
|
||||||
@@ -52,14 +65,14 @@ library behavior or an Audita domain requirement, the proposed adaptation or
|
|||||||
upstream request, and its acceptance evidence. Distinguish agreed decisions from
|
upstream request, and its acceptance evidence. Distinguish agreed decisions from
|
||||||
recommendations. No upstream request has been submitted by this planning work.
|
recommendations. No upstream request has been submitted by this planning work.
|
||||||
|
|
||||||
## Baseline and Reviewed Dependency Set
|
## Baseline and Selected Dependency Set
|
||||||
|
|
||||||
The reviewed application revision is
|
The reviewed application revision is
|
||||||
`cbcb1b3778d747ced7825d09d9e7536cabc0f0fa`. Its [module file](../../go.mod)
|
`cbcb1b3778d747ced7825d09d9e7536cabc0f0fa`. Its [module file](../../go.mod)
|
||||||
uses old-path ConfigKit v0.7.1 and PromptKit v0.14.0, with no CommandKit.
|
uses old-path ConfigKit v0.7.1 and PromptKit v0.14.0, with no CommandKit.
|
||||||
The source minimum is Go 1.26.0; the release runbook selects Go 1.26.8.
|
The source minimum is Go 1.26.0; the release runbook selects Go 1.26.8.
|
||||||
|
|
||||||
The reviewed targets are published and mutually aligned:
|
The following targets were reviewed as published and mutually aligned:
|
||||||
|
|
||||||
| Module | Version | Reviewed source commit |
|
| Module | Version | Reviewed source commit |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
@@ -77,19 +90,28 @@ the core tag's guide predates integration publication. The former missing
|
|||||||
an ordinary compatibility review, not an assumption that later releases are
|
an ordinary compatibility review, not an assumption that later releases are
|
||||||
interchangeable.
|
interchangeable.
|
||||||
|
|
||||||
|
ReleaseKit v0.9.0 at `go.maximumdirect.net/releasekit` is also a required target.
|
||||||
|
The library graph already brings in that version, but Audita's direct tool still
|
||||||
|
uses old-path v0.4.1. Direct adoption includes reviewing the v0.9.0 release and
|
||||||
|
validator APIs; the earlier integration checks do not establish its suitability
|
||||||
|
for Audita's complete release workflow.
|
||||||
|
|
||||||
## Proposed Order of Operations
|
## Proposed Order of Operations
|
||||||
|
|
||||||
1. **Resolve the target contracts across all three outlines.** Establish the
|
1. **Resolve the target contracts across all four libraries.** Establish the
|
||||||
standard command inventory, discovery behavior, source ownership, and
|
standard command inventory, discovery behavior, source ownership, and
|
||||||
reporting expectations before implementation. Identify concrete upstream
|
reporting and release-workflow expectations before implementation. Identify
|
||||||
requests early; do not postpone CommandKit design until the runtime is done.
|
concrete upstream requests early; do not postpone CommandKit design until the
|
||||||
|
runtime is done.
|
||||||
Reconcile planned changes with the current architecture policy, especially
|
Reconcile planned changes with the current architecture policy, especially
|
||||||
application-only credential rules, finite admission, and preference for
|
application-only credential rules, finite admission, and preference for
|
||||||
standard-library CLI parsing. Update policies with adopted behavior; do not
|
standard-library CLI parsing. Update policies with adopted behavior; do not
|
||||||
silently treat old integration choices as permanent requirements.
|
silently treat old integration choices as permanent requirements.
|
||||||
2. **Prepare toolchain and migration work.** Select Go 1.27 or newer, updating
|
2. **Prepare toolchain and migration work.** Select Go 1.27 or newer, updating
|
||||||
source/build requirements, CI/bootstrap assumptions, release instructions,
|
source/build requirements, CI/bootstrap assumptions, release instructions,
|
||||||
and toolchain attribution. Inventory operator file and CLI migration needs.
|
and toolchain attribution. Upgrade the direct ReleaseKit tool, launcher, and
|
||||||
|
version integration to v0.9.0, implementing the release-machinery work below.
|
||||||
|
Inventory operator file and CLI changes for hard-cutover guidance.
|
||||||
Keep implementation units focused; no intermediate public release is needed.
|
Keep implementation units focused; no intermediate public release is needed.
|
||||||
3. **Coordinate the ConfigKit and PromptKit cutover.** Change both module
|
3. **Coordinate the ConfigKit and PromptKit cutover.** Change both module
|
||||||
identities and their exchanged types together, then implement native resource
|
identities and their exchanged types together, then implement native resource
|
||||||
@@ -102,17 +124,43 @@ interchangeable.
|
|||||||
5. **Validate and document the assembled application.** Complete the offline
|
5. **Validate and document the assembled application.** Complete the offline
|
||||||
behavioral checks from the outlines and the full Audita suite. Update canonical
|
behavioral checks from the outlines and the full Audita suite. Update canonical
|
||||||
configuration, CLI, operations, integration, and internal documentation with
|
configuration, CLI, operations, integration, and internal documentation with
|
||||||
implementation; provide maintained examples and operator migration guidance.
|
implementation; provide maintained examples and hard-cutover guidance. Validate
|
||||||
|
the adopted release workflow without publishing a release.
|
||||||
6. **Prepare the next major release.** Public configuration, inspection, and CLI
|
6. **Prepare the next major release.** Public configuration, inspection, and CLI
|
||||||
changes warrant a major release under [release policy](../policy/release.md).
|
changes warrant a major release under [release policy](../policy/release.md).
|
||||||
Exact numbering and publication timing remain release-preparation work. Use
|
Exact numbering and publication timing remain release-preparation work. Use
|
||||||
the existing release process without importing upstream release gates.
|
the adopted ReleaseKit workflow and selected upstream validators; document
|
||||||
|
required operator changes without requiring a compatibility transition period.
|
||||||
|
|
||||||
Separate outlines organize responsibility; they do not make the dependency
|
Separate outlines organize responsibility; they do not make the dependency
|
||||||
migration independent. The two ConfigKit import identities have distinct Go
|
migration independent. The two ConfigKit import identities have distinct Go
|
||||||
named types. Early upstream investigation can proceed before the dependent
|
named types. Early upstream investigation can proceed before the dependent
|
||||||
implementation stage is ready.
|
implementation stage is ready.
|
||||||
|
|
||||||
|
## ReleaseKit Adoption Work
|
||||||
|
|
||||||
|
1. Review v0.9.0's supported release workflow, validators, and version integration.
|
||||||
|
Inventory Audita's launcher, scripts, CI responsibilities, and local release
|
||||||
|
checks against those facilities. Select the best target workflow without
|
||||||
|
preserving old invocation or validation behavior for compatibility.
|
||||||
|
2. Move the direct tool and version integration to the new module identity.
|
||||||
|
Replace local orchestration and validation with supported ReleaseKit facilities
|
||||||
|
wherever possible. Keep repository-specific configuration and necessary domain
|
||||||
|
integration; remove redundant wrappers and checks.
|
||||||
|
3. Select ReleaseKit-owned validators freely according to the desired workflow;
|
||||||
|
there is no numerical limit or presumption against adopting upstream checks.
|
||||||
|
For every retained local release validator, record its domain-specific purpose
|
||||||
|
and why upstream facilities do not satisfy it. Remove checks without that
|
||||||
|
justification, and propose reusable missing capabilities upstream.
|
||||||
|
4. Reconcile the release policy and runbook with the selected workflow as it lands,
|
||||||
|
including provisions that would otherwise restrict the chosen upstream
|
||||||
|
validators. Update CI, version reporting, and attribution as needed. The
|
||||||
|
current runbook is a baseline to replace, not a compatibility constraint.
|
||||||
|
5. Verify the selected validators, version identity, and release orchestration
|
||||||
|
through non-publishing checks. Cover any justified domain validation and verify
|
||||||
|
that removed local checks are no longer duplicated around upstream validation.
|
||||||
|
Adoption work does not authorize publishing a release.
|
||||||
|
|
||||||
## Shared Evidence, Validation, and Completion
|
## Shared Evidence, Validation, and Completion
|
||||||
|
|
||||||
The review verified release identities, requirements, and relevant upstream
|
The review verified release identities, requirements, and relevant upstream
|
||||||
@@ -131,28 +179,16 @@ provider calls and do not prove migrated Audita behavior or cross-platform
|
|||||||
execution. Use controlled provider boundaries and proportionate tests under
|
execution. Use controlled provider boundaries and proportionate tests under
|
||||||
[testing policy](../policy/testing.md); live diagnostics are not release gates.
|
[testing policy](../policy/testing.md); live diagnostics are not release gates.
|
||||||
|
|
||||||
Completion requires all three adoption targets, resolved decisions, migrated
|
Completion requires all four adoption targets, resolved decisions, migrated
|
||||||
examples, useful native inspection, preserved domain behavior, and a passing
|
examples, useful native inspection, the selected domain behavior, a passing
|
||||||
assembled application. Upstream requests need an explicit disposition before
|
assembled application, and the adopted ReleaseKit workflow. Every retained local
|
||||||
calling the dependent behavior complete. Any temporary workaround must name its
|
release validator must have a domain-specific justification. Acceptance tests
|
||||||
reason and removal condition; it is not architecture by default.
|
must assert the target contracts; update or remove tests whose sole purpose is
|
||||||
|
preserving superseded behavior. Upstream requests need an explicit disposition
|
||||||
|
before calling the dependent behavior complete. Any temporary workaround must
|
||||||
|
name its reason and removal condition; it is not architecture by default.
|
||||||
|
|
||||||
Refresh [attribution](../oss/attribution.md) for the exact selected dependencies
|
Refresh [attribution](../oss/attribution.md) for the exact selected dependencies
|
||||||
and toolchain under [OSS policy](../policy/oss.md). The reviewed library grants
|
and toolchain under [OSS policy](../policy/oss.md). The reviewed library grants
|
||||||
remain LGPL-3.0-or-later; remove old catalog entries when no longer incorporated
|
remain LGPL-3.0-or-later; remove old catalog entries when no longer incorporated
|
||||||
and retain shared license texts. Do not copy upstream policy inventories.
|
and retain shared license texts. Do not copy upstream policy inventories.
|
||||||
|
|
||||||
## Open Decisions
|
|
||||||
|
|
||||||
### Direct ReleaseKit Migration
|
|
||||||
|
|
||||||
**Recommendation:** assess the direct ReleaseKit tool and launcher in a distinct
|
|
||||||
preparation unit, coordinating its import identity and version reporting if the
|
|
||||||
new tool is adopted. The library graph brings new-path ReleaseKit v0.9.0 but does
|
|
||||||
not migrate Audita's old-path v0.4.1 tool. Explicit treatment avoids accidental
|
|
||||||
release behavior changes and makes the duplicate identities understandable.
|
|
||||||
|
|
||||||
**Alternative:** migrate ReleaseKit within the same toolchain unit. This reduces
|
|
||||||
duplicate module identities sooner and may simplify attribution, but broadens
|
|
||||||
that unit into release-workflow compatibility work. Neither choice authorizes
|
|
||||||
adopting upstream publication gates or publishing a release during implementation.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user