Prepare source release validation
This commit is contained in:
@@ -2,8 +2,8 @@
|
||||
|
||||
## Status and ownership
|
||||
|
||||
Status: implementation in progress; Stages 1–15 are complete and later stages are
|
||||
pending.
|
||||
Status: implementation complete; Stages 1–22 are complete. Release-candidate
|
||||
selection and publication remain separate maintainer work.
|
||||
|
||||
Audience: a `gpt-5.6-terra` coding agent implementing one stage per prompt, in
|
||||
ascending order. Each stage depends on every earlier stage being complete.
|
||||
@@ -85,7 +85,7 @@ the adapter, YAML-policy, diagnostics, limits, and rendering regressions. A fina
|
||||
upstream version is preferred when it passes those checks; if the RC is retained,
|
||||
record that decision in release readiness and compatibility review.
|
||||
|
||||
Follow the feature's [upstream isolation contract](initial.md#yaml-dependency-and-public-api-isolation).
|
||||
Follow the feature's [upstream isolation contract](../policy/architecture.md#public-api-and-dependency-direction).
|
||||
Translate upstream API changes internally without changing ConfigKit declarations
|
||||
or consumer requirements. Never re-export upstream aliases/options/plugins, expose
|
||||
parser errors through wrapping, or pass parser-created objects through `any`.
|
||||
@@ -97,8 +97,8 @@ unverified upstream versions or add a selectable-parser framework.
|
||||
### Updated extraction map
|
||||
|
||||
Use the source revisions and adaptation policies owned by the feature's
|
||||
[foundation](initial.md#existing-implementation-foundation) and
|
||||
[secret bootstrap](initial.md#secret-references-and-explicit-bootstrap) sections.
|
||||
[foundation](../internal/extraction.md) and
|
||||
[secret bootstrap](../config.md#typed-secret-references) sections.
|
||||
Paths below are relative to the named sibling repository. Reinspect them in
|
||||
Stage 1 and record the exact revision actually copied. The maintainer is the sole
|
||||
author of the relevant application code and has authorized its reuse and relicensing
|
||||
@@ -154,9 +154,9 @@ syscall-level confinement, path discovery, or a public filesystem-provider API.
|
||||
|
||||
### Secret, override, and history implementation bounds
|
||||
|
||||
Follow the feature contracts for [secrets](initial.md#secret-references-and-explicit-bootstrap),
|
||||
[CLI overrides](initial.md#cli-overrides), and
|
||||
[explanation](initial.md#historical-value-explanation). Introduce these public APIs
|
||||
Follow the feature contracts for [secrets](../config.md#typed-secret-references),
|
||||
[CLI overrides](../config.md#explicit-cli-overrides), and
|
||||
[explanation](../config.md#historical-value-explanation). Introduce these public APIs
|
||||
only in Stages 16–19. Earlier stages cover ordinary types and file/profile layers;
|
||||
they must not expose an unresolved secret as a completed load or silently accept
|
||||
an override option. Extend the shared descriptor/projection graph for `Secret`
|
||||
@@ -303,8 +303,8 @@ Completion evidence (2026-09-06):
|
||||
No deviations were required. Paths, diagnostics, parsing, and all later behavior
|
||||
remain assigned to subsequent stages.
|
||||
|
||||
Read: feature [foundation](initial.md#existing-implementation-foundation),
|
||||
[consumer fit](initial.md#consumer-fit-and-intentional-migrations), all policies.
|
||||
Read: feature [foundation](../internal/extraction.md),
|
||||
[consumer fit](../consumers/README.md), all policies.
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -353,8 +353,8 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
metadata population and configuration lifecycle behavior remain later work.
|
||||
|
||||
Read: feature [paths](initial.md#paths-and-presence),
|
||||
[diagnostics](initial.md#provenance-diagnostics-and-redaction), public metadata API.
|
||||
Read: feature [paths](../config.md#layered-metadata),
|
||||
[diagnostics](../config.md#safe-failures), public metadata API.
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -408,8 +408,8 @@ Completion evidence (2026-09-06):
|
||||
`go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on linux/amd64. No
|
||||
deviations were required; typed binding and decoding remain later work.
|
||||
|
||||
Read: feature [YAML policy](initial.md#yaml-and-scalar-policy),
|
||||
[source constructors](initial.md#entry-point-and-reusable-application-definition).
|
||||
Read: feature [YAML policy](../config.md#yaml-documents),
|
||||
[source constructors](../config.md#single-source-loading).
|
||||
|
||||
Start with the extraction map's parser and strict-loader cases; the old
|
||||
second-document acceptance defect is already fixed in Narratio.
|
||||
@@ -485,8 +485,8 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
typed value operations remain later work.
|
||||
|
||||
Read: feature [typed decoding](initial.md#typed-decoding) and
|
||||
[type/projection contract](initial.md#supported-types-and-projection).
|
||||
Read: feature [typed decoding](../config.md#defaults-and-typed-decoding) and
|
||||
[type/projection contract](../config.md#application-schema-binding).
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -537,8 +537,8 @@ Completion evidence (2026-09-06):
|
||||
Go 1.26.7 on linux/amd64. No deviations were required; defaults and typed decoding
|
||||
remain later work.
|
||||
|
||||
Read: feature [ownership](initial.md#recorded-resolution-and-validation) and
|
||||
[type/projection contract](initial.md#supported-types-and-projection).
|
||||
Read: feature [ownership](../config.md#recorded-application-resolution) and
|
||||
[type/projection contract](../config.md#application-schema-binding).
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -590,7 +590,7 @@ Completion evidence (2026-09-06):
|
||||
and `git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
public loading and schema-version checks remain later work.
|
||||
|
||||
Read: feature [defaults/null](initial.md#static-defaults-and-null) and typed decoding.
|
||||
Read: feature [defaults/null](../config.md#defaults-and-typed-decoding) and typed decoding.
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -651,9 +651,9 @@ Completion evidence (2026-09-06):
|
||||
`go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on linux/amd64. No
|
||||
deviations were required; resolution and semantic validation remain later work.
|
||||
|
||||
Read: feature [lifecycle](initial.md#resolution-lifecycle),
|
||||
[version hook](initial.md#schema-checking-and-secret-classification),
|
||||
[results](initial.md#results-errors-and-inspection).
|
||||
Read: feature [lifecycle](../config.md#single-source-loading),
|
||||
[version hook](../config.md#application-schema-binding),
|
||||
[results](../config.md#safe-failures).
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -715,7 +715,7 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
semantic validation remains later work.
|
||||
|
||||
Read: feature [resolution callbacks](initial.md#resolution-and-validation-callbacks).
|
||||
Read: feature [resolution callbacks](../config.md#recorded-application-resolution).
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -776,8 +776,8 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
imports and profiles remain deliberately unavailable.
|
||||
|
||||
Read: feature [diagnostic callbacks](initial.md#resolution-and-validation-callbacks)
|
||||
and [schema reports](initial.md#schema-checking-and-secret-classification).
|
||||
Read: feature [diagnostic callbacks](../config.md#recorded-application-resolution)
|
||||
and [schema reports](../config.md#application-schema-binding).
|
||||
|
||||
Tasks:
|
||||
|
||||
@@ -824,7 +824,7 @@ Completion evidence (2026-09-06):
|
||||
[current composition contract](../config.md#strict-document-composition) owns the
|
||||
implemented semantics; public import wiring remains deferred to subsequent work.
|
||||
|
||||
Read: feature [composition table](initial.md#composition-and-overlay).
|
||||
Read: feature [composition table](../config.md#strict-document-composition).
|
||||
|
||||
Extract Narratio's additive composer and conflict tests before writing equivalent
|
||||
code. Change empty-map expectations to the feature table and retain exact locations.
|
||||
@@ -883,7 +883,7 @@ Completion evidence (2026-09-06):
|
||||
`go test -race ./...`, `go vet ./...`, `go build ./...`, `go mod tidy -diff`, and
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64.
|
||||
|
||||
Read: feature [import graph](initial.md#explicit-imports-and-source-identity).
|
||||
Read: feature [import graph](../config.md#explicit-imports).
|
||||
|
||||
Extract the flat import loader and tests, then generalize its graph, identity and
|
||||
containment rules. Do not treat its root-only declarations as ConfigKit's contract.
|
||||
@@ -1008,7 +1008,7 @@ Completion evidence (2026-09-06):
|
||||
Verified `go test ./...`, `go test -race ./...`, `go vet ./...`, `go build ./...`,
|
||||
and `git diff --check` with Go 1.26.7 on linux/amd64.
|
||||
|
||||
Read: feature [profiles](initial.md#profiles), composition/overlay table.
|
||||
Read: feature [profiles](../config.md#selected-profiles), composition/overlay table.
|
||||
|
||||
Extract Narratio's overlay mechanics and profile tests; preserve the intentional
|
||||
null/kind and profile-selection differences listed in the feature roadmap.
|
||||
@@ -1064,8 +1064,8 @@ Completion evidence (2026-09-06):
|
||||
Verified `go test ./...`, `go test -race ./...`, `go vet ./...`, `go build ./...`,
|
||||
`go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on linux/amd64.
|
||||
|
||||
Read: feature [presence](initial.md#paths-and-presence),
|
||||
[history](initial.md#provenance-diagnostics-and-redaction), metadata API.
|
||||
Read: feature [presence](../config.md#layered-metadata),
|
||||
[history](../config.md#safe-failures), metadata API.
|
||||
|
||||
Use Narratio's effective ownership and inspection tests as extraction evidence.
|
||||
Its source-only records need locations and complete historical operations.
|
||||
@@ -1123,8 +1123,8 @@ Completion evidence (2026-09-06):
|
||||
`go build ./...`, `go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on
|
||||
linux/amd64.
|
||||
|
||||
Read: feature [redaction](initial.md#provenance-diagnostics-and-redaction),
|
||||
[secret predicate](initial.md#schema-checking-and-secret-classification), result API.
|
||||
Read: feature [redaction](../config.md#safe-failures),
|
||||
[secret predicate](../config.md#application-schema-binding), result API.
|
||||
|
||||
Reuse Narratio's deterministic effective-output and non-disclosure cases. Render
|
||||
from the owned typed projection, without its marshal/parse reconstruction.
|
||||
@@ -1195,7 +1195,7 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
environment-backed typed secret references remain later work.
|
||||
|
||||
Read: [secret bootstrap contract](initial.md#secret-references-and-explicit-bootstrap),
|
||||
Read: [secret bootstrap contract](../config.md#typed-secret-references),
|
||||
architecture responsibility boundary, testing policy, and WeatherReporter's
|
||||
`internal/config/secrets.go` and corresponding `config_test.go` cases; also
|
||||
Narratio's `internal/app/secrets_env.go`, its tests, and bounded-read helper.
|
||||
@@ -1267,7 +1267,7 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
CLI overrides remain later work.
|
||||
|
||||
Read: [secret reference contract](initial.md#secret-references-and-explicit-bootstrap),
|
||||
Read: [secret reference contract](../config.md#typed-secret-references),
|
||||
shared descriptor/projection rules and lifecycle, Stage 16 report boundary.
|
||||
|
||||
Tasks:
|
||||
@@ -1337,7 +1337,7 @@ Completion evidence (2026-09-06):
|
||||
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
|
||||
safe historical-value explanation remains later work.
|
||||
|
||||
Read: [override contract](initial.md#cli-overrides), overlay/presence/version rules,
|
||||
Read: [override contract](../config.md#explicit-cli-overrides), overlay/presence/version rules,
|
||||
source ordering, and the secret-reference boundary.
|
||||
|
||||
Tasks:
|
||||
@@ -1403,7 +1403,7 @@ Completion evidence (2026-09-06):
|
||||
`go build ./...`, `go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on
|
||||
linux/amd64. No deviations were required; consumer ergonomics remain later work.
|
||||
|
||||
Read: [explanation contract](initial.md#historical-value-explanation), redaction
|
||||
Read: [explanation contract](../config.md#historical-value-explanation), redaction
|
||||
rules, and history bounds above.
|
||||
|
||||
Generalize Narratio's semantic-record and inspection tests. They cover effective
|
||||
@@ -1598,7 +1598,47 @@ Acceptance:
|
||||
|
||||
## Stage 22 — Prepare release validation and reconcile documentation
|
||||
|
||||
Status: pending.
|
||||
Status: complete.
|
||||
|
||||
Completion evidence (2026-09-06):
|
||||
|
||||
- Added the [maintainer release procedure](../release.md) for the existing
|
||||
`origin/main`, module `gitea.maximumdirect.net/eric/ConfigKit`, source-only stable
|
||||
tags, Go 1.25 minimum and newer-toolchain validation, and Linux/macOS amd64/arm64
|
||||
targets. It supplies candidate recording, clean branch/index/worktree and exact
|
||||
remote-commit guards, version/release-note/tag checks, precise single-ref tag
|
||||
publication, clean consumer retrieval without `replace`, and immutable correction
|
||||
steps. Private-host access is a prerequisite without embedding credentials or
|
||||
environment dumps.
|
||||
- Added fail-fast [`scripts/release-check.sh`](../../scripts/release-check.sh). It
|
||||
verifies cached dependencies and runs offline disposable-copy module hygiene,
|
||||
default tests on Go 1.25.5 and Go 1.26.7, vet and native builds on both, a native
|
||||
race run, CGO-disabled builds for linux/amd64, linux/arm64, darwin/amd64, and
|
||||
darwin/arm64, repository-wide Go formatting and text whitespace including
|
||||
untracked files, executable examples, consumer fixtures, public import isolation,
|
||||
and local documentation links. Toolchain/dependency acquisition remains an
|
||||
explicit preceding runbook step.
|
||||
- Added `TestLocalDocumentationLinks`, which strictly verifies repository-local files
|
||||
and Markdown headings while treating recorded sibling-source links as applicable
|
||||
only when those optional checkouts exist. The runbook makes immutable extraction
|
||||
revisions authoritative in isolated release clones.
|
||||
- Reconciled README, development, configuration, consumer, architecture/testing/
|
||||
documentation/release policies, component and extraction inventories, and ADR
|
||||
navigation with current behavior. Reduced the implemented feature roadmap to a
|
||||
target record linking current owners and retaining only foundations plus explicit
|
||||
non-goals/deferred scope. The implementation plan and readiness record remain until
|
||||
an actual candidate retires completed roadmap files as required by release policy.
|
||||
- Reassessed the YAML v4 dependency with `go list -m -versions` and
|
||||
`go list -m -json ...@latest`; `v4.0.0-rc.6` remained the newest available release
|
||||
on 2026-09-06, so the tested explicit pin was retained. `go doc -all` and
|
||||
`TestDependencyImportBoundary` confirmed public documentation is renderable and no
|
||||
upstream YAML type/import leaks outside the private adapter or maintained examples.
|
||||
- The complete checker passed on linux/amd64 with Go 1.25.5 and Go 1.26.7. The
|
||||
[release-readiness evidence](release-readiness.md) keeps exact candidate/release
|
||||
note, native macOS execution, compatibility/content approval, roadmap retirement,
|
||||
authoritative remote/tag guards, and post-publication retrieval explicitly open
|
||||
under the revised bootstrap exception. No tag, push, downstream migration, release
|
||||
note, or publication occurred.
|
||||
|
||||
Read: release policy in full and [release-readiness gaps](release-readiness.md).
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -2,24 +2,36 @@
|
||||
|
||||
## Status and ownership
|
||||
|
||||
ConfigKit is not release-ready. This document tracks outstanding release
|
||||
prerequisites under the [temporary bootstrap exception](../policy/release.md#temporary-bootstrap-deferral).
|
||||
It is not the library implementation plan and does not assign implementation
|
||||
stages. The maintainer preparing the first release owns closure.
|
||||
ConfigKit's implementation is prepared for release-candidate validation, but no
|
||||
release candidate has been selected or publication authorized. The maintainer
|
||||
preparing the first release owns the remaining gates under the
|
||||
[temporary bootstrap exception](../policy/release.md#temporary-bootstrap-deferral).
|
||||
This evidence record remains until candidate preparation retires completed roadmap
|
||||
material in favor of the operational [release procedure](../release.md) and normal
|
||||
release notes.
|
||||
|
||||
## Outstanding prerequisites
|
||||
## Preparation evidence
|
||||
|
||||
| Gap | Evidence required to close |
|
||||
| Preparation item | Status and evidence |
|
||||
| --- | --- |
|
||||
| No Go module or declared support matrix | Established module path, supported Go versions and platform targets documented in the release procedure |
|
||||
| No release runbook | `docs/release.md` exists with the prerequisites, commands, publication guards, and verification required by release policy |
|
||||
| No complete release checker | A documented command exists and exercises every applicable automated candidate gate; manual gates and inapplicable checks are explicit |
|
||||
| No consumer verification procedure | Runbook verifies retrieval of the exact released module version and a representative consumer build without local replacement directives |
|
||||
| No verified secret/precedence/explanation contracts | Current contracts and passing bootstrap skip/partial-failure, secret isolation, CLI precedence, and safe historical-value regressions; representative consumer examples |
|
||||
| No validated release candidate | Version-matched release note, current contracts/examples, and complete checks against the exact committed candidate |
|
||||
| Module and support matrix | Closed: the runbook records module `gitea.maximumdirect.net/eric/ConfigKit`, minimum Go 1.25 with a patched 1.25 plus newer supported toolchain, and Linux/macOS on amd64/arm64. |
|
||||
| Maintainer release procedure | Closed: `docs/release.md` owns access prerequisites, candidate recording, complete validation, exact remote/commit/tag guards, source-only publication, consumer retrieval, and correction. |
|
||||
| Automated source checker | Closed for current-source preparation: `scripts/release-check.sh` passed on 2026-09-06 with Go 1.25.5 and Go 1.26.7 on linux/amd64. It performs disposable-copy module hygiene, cached/offline tests, race, vet, native and four-target cross-builds, formatting/whitespace, examples, import isolation, and local-link gates. The exact candidate must rerun it. |
|
||||
| Consumer verification procedure | Closed as procedure: the runbook retrieves an exact published version into a clean temporary module with no local replacement and tests/builds it. Actual retrieval remains a post-publication gate. |
|
||||
| Secret/precedence/explanation evidence | Closed locally: current contracts and deterministic tests cover bootstrap skip/partial failure, credential isolation, defaults/base/profile/CLI precedence, historical redaction, and maintained consumer startup examples. |
|
||||
| Parser dependency reassessment | Closed for preparation: on 2026-09-06, `go list -m -versions go.yaml.in/yaml/v4` and `go list -m -json go.yaml.in/yaml/v4@latest` both showed `v4.0.0-rc.6` as the newest available release. The explicit pin is retained; a candidate compatibility review must reassess and record it again. |
|
||||
|
||||
No release can proceed while these prerequisites remain open. Close items only
|
||||
on evidence from actual files and checks, not proposed commands. Record closure
|
||||
evidence here while this roadmap remains active. Once all gaps are closed,
|
||||
remove the bootstrap exception and retire this document in favor of the
|
||||
operational runbook and normal release records.
|
||||
## Outstanding release gates
|
||||
|
||||
| Gate | Owner and closure evidence |
|
||||
| --- | --- |
|
||||
| Exact candidate and release note | Maintainer selects an unused stable version, writes `docs/releases/<version>.md`, commits all release changes, runs the checker against that exact clean commit, pushes it to `origin/main`, and records the commit. |
|
||||
| Native platform execution | Maintainer records applicable checker, race, symlink, and permission-fixture results on native Linux and macOS. Current local evidence is Linux/amd64 only; cross-builds do not close macOS execution. |
|
||||
| Compatibility, migration, and content review | Maintainer records public API/configuration/diagnostic review, downstream migration impact, release-note approval, and inspection for credentials, private data, generated output, unintended files, and unrelated changes. |
|
||||
| Roadmap retirement | Maintainer removes obsolete completed files under `docs/roadmap/`, repairs inbound links, and reruns the checker as part of the candidate. This record and the implementation plan intentionally remain while no candidate exists. |
|
||||
| Remote publication guards | Maintainer fetches authoritative `origin/main` and tags immediately before publication and proves branch, clean worktree/index, candidate commit, remote commit, release note, approvals, and unused version all agree. |
|
||||
| Tag and retrieval verification | After authorization, maintainer pushes only the exact immutable source tag, verifies its peeled remote commit, and retrieves/tests/builds the exact version in a clean consumer module without `replace`. |
|
||||
|
||||
No tag, push, downstream migration, release note, or release publication was
|
||||
performed during implementation. A green local checker does not close the exact
|
||||
candidate, native macOS, remote, or post-publication gates.
|
||||
|
||||
Reference in New Issue
Block a user