300 lines
14 KiB
Markdown
300 lines
14 KiB
Markdown
# ReleaseKit v0.2.0 roadmap
|
||
|
||
Status: Implemented and locally verified. Stages 1–15 are complete; see the
|
||
[implementation plan](implementation.md) for the completion record. Audita's
|
||
module-selected local and CI integration is committed at `17421bc`. Broader
|
||
consumer adoption, architecture review, hosted deployment, and release tagging
|
||
remain separate work.
|
||
|
||
This roadmap catalogs improvements to ReleaseKit v0.1.0. Each item records its
|
||
rationale, target state, and relevant scope decisions. The
|
||
[implementation plan](implementation.md) owns the staged work and verification
|
||
evidence.
|
||
|
||
The priorities in [ADR 0002](../adr/0002-routine-releases.md) guide this work:
|
||
minimize application-owned release code, duplicated mechanics, and routine
|
||
developer decisions through a standard, minimal API.
|
||
|
||
## 1. Establish the shared validation API and profile model
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
The shared validation foundation and its remediation are complete. ReleaseKit
|
||
has common candidate execution, facade-owned diagnostics, committed-file
|
||
inspection, and a product-specific additional-check extension point. The
|
||
optional v0.2.0 capabilities now have functioning API/profile selections and
|
||
checker implementations.
|
||
|
||
The [validation-model roadmap](model.md) records this enabling work and its
|
||
rationale. A common model lets consumers declare choices once and receive
|
||
ReleaseKit's shared execution and coordination.
|
||
|
||
### Target end state
|
||
|
||
A facade-owned validation specification and corresponding profile object
|
||
express the agreed optional checks with consistent defaults and behavior.
|
||
ReleaseKit owns coordination and diagnostics through the existing `Check` and
|
||
`Publish` operations. Product-specific checks, publication expectations,
|
||
artifact builds, and delivery retain their distinct responsibilities.
|
||
|
||
The implemented API and profile provide equivalent declarations for the
|
||
validation capabilities below through the existing shared foundation.
|
||
|
||
## 2. Use the application's module-selected ReleaseKit version in CI
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
At the v0.1.0 planning baseline, the maintained CI template selected ReleaseKit
|
||
through a separate `RELEASEKIT_VERSION` value and invoked its command with an
|
||
explicit `@version`.
|
||
|
||
Audita demonstrates the resulting duplication: its local release wrapper builds
|
||
ReleaseKit using the application's module dependencies, while CI independently
|
||
selects ReleaseKit v0.1.0. A dependency upgrade can leave CI using an older tool.
|
||
Maintainers must remember to coordinate both declarations.
|
||
|
||
Using the application's module-selected version for both paths gives upgrades
|
||
one dependency declaration and keeps local publication and CI delivery aligned.
|
||
Stages 12–14 changed the maintained template and Audita's workflow to this
|
||
approach; the current [adoption guidance](../consumers/delivery.md#woodpecker-tag-workflows)
|
||
describes it.
|
||
|
||
### Target end state
|
||
|
||
For applications that declare ReleaseKit as a module dependency, the standard
|
||
CI integration uses the ReleaseKit version selected by the released source's
|
||
module configuration. The workflow verifies the triggering tag and commit and
|
||
checks out that source before resolving and building the release tool.
|
||
|
||
Local publication and CI delivery use the same module-based selection approach.
|
||
Updating the application's ReleaseKit dependency updates both paths. The
|
||
consumer workflow supplies the CI event, environment, and credentials; the
|
||
application profile continues to supply product and delivery settings.
|
||
|
||
Tool bootstrap and dependency preparation remain distinct from offline
|
||
validation and builds. Source publication and hosted delivery retain separate
|
||
outcomes. ReleaseKit's own source bootstrap and consumers using a separately
|
||
installed tool remain supported use cases.
|
||
|
||
Audita adopted the module-based integration as the first consumer migration in
|
||
commit `17421bc`.
|
||
|
||
The maintained template and Audita's first migration now use one ReleaseKit
|
||
module declaration for local and hosted integration.
|
||
|
||
## 3. Select one base test invocation, including race testing
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
ReleaseKit always runs its standard offline Go suite before additional product
|
||
checks. ConfigKit selects race-enabled testing for its release validation.
|
||
PromptKit requests the same capability for its concurrent execution and
|
||
backend-capacity management.
|
||
Expressing that selection as an additional check would execute the suite twice
|
||
and leave the application coordinating shared validation mechanics.
|
||
|
||
A small declarative selection lets consumers retain their chosen validation
|
||
while ReleaseKit owns the procedure and runs the suite once.
|
||
|
||
### Target end state
|
||
|
||
The public Go API and profile support selecting race testing for the single
|
||
base Go test invocation. With no selection, the current default applies.
|
||
`Check` and `Publish`, including their CLI forms, use the same selection.
|
||
|
||
ReleaseKit constructs the invocation and owns candidate capture, full-suite
|
||
scope, offline execution, ordering, and failure reporting. Additional product
|
||
checks remain available after shared validation. Selecting race testing reports
|
||
unavailable prerequisites clearly and preserves the selected validation.
|
||
|
||
The API and profile now let ConfigKit and PromptKit select a race-enabled suite
|
||
once and remove the corresponding consumer-owned test invocation when they
|
||
adopt the selection.
|
||
|
||
## 4. Offer a separate full vet pass
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
ConfigKit and PromptKit currently run a full `go vet` pass in addition to their
|
||
test suites. ReleaseKit relies on test-time vet unless a consumer supplies an
|
||
additional command. That leaves consumers coordinating vet coverage and
|
||
repeated work.
|
||
|
||
### Target end state
|
||
|
||
A public API and profile option selects a separate full vet pass within shared
|
||
candidate validation. ReleaseKit automatically omits test-time vet when that
|
||
pass is selected. The base suite runs once, followed by the selected vet pass,
|
||
with failures reported through the ordinary check and publication flow.
|
||
|
||
The option preserves current defaults for consumers that leave it unset.
|
||
ReleaseKit owns the offline command and its coordination with base testing.
|
||
|
||
The API and profile now support replacing ConfigKit's and PromptKit's separate
|
||
vet commands and manual test-time vet settings with one declarative choice.
|
||
|
||
## 5. Verify package compilation for selected targets
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
ReleaseKit's existing build declaration selects executable artifacts and their
|
||
delivery. ConfigKit is a source-only library that checks package compilation
|
||
for Linux amd64 and arm64. Its current release script owns the cross-target
|
||
build loop even though the underlying mechanics are shared across consumers.
|
||
|
||
### Target end state
|
||
|
||
The public API and profile can declare optional package-compilation targets
|
||
independently of executable artifacts. ReleaseKit compiles the module's packages
|
||
for those targets within candidate validation, after the selected test and vet
|
||
work. `Check` and `Publish` share this behavior and report compilation failures
|
||
through their existing outcomes.
|
||
|
||
Package compilation uses the existing pure-Go build baseline (`CGO_ENABLED=0`).
|
||
|
||
A source-only library retains page-only delivery. Package-compilation checks
|
||
require no binary name, version smoke command, or artifact manifest. Successful
|
||
compilation establishes build compatibility; execution on a target remains a
|
||
separate concern. Consumers select targets for their support commitments.
|
||
|
||
The API and profile now let ConfigKit declare its two Linux targets and remove
|
||
its release-specific compilation loop when it adopts the selection.
|
||
|
||
## 6. Check an optional expected publication endpoint
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
ReleaseKit resolves and captures the selected remote's push endpoint and
|
||
rechecks it during publication. ConfigKit additionally declares an expected
|
||
authoritative destination in its release script. Retaining that expectation
|
||
outside ReleaseKit would duplicate destination-resolution work.
|
||
|
||
### Target end state
|
||
|
||
An optional public API and profile setting declares the expected publication
|
||
destination. `Publish` compares it exactly with the effective push URL resolved
|
||
by Git before candidate validation and publication. A mismatch produces a clear
|
||
failure.
|
||
The existing captured-endpoint, recheck, and recovery machinery continues to
|
||
govern the operation.
|
||
|
||
The expectation applies to the publication destination. Fetch configuration
|
||
retains its existing semantics, and `Check` retains its local-only behavior.
|
||
Consumers that omit the expectation keep the current remote-selection model.
|
||
|
||
Consumers can now declare the intended push destination without maintaining
|
||
their own publication preflight logic.
|
||
|
||
## 7. Offer Go formatting validation
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
PromptKit maintains a shell loop that enumerates tracked Go files and checks
|
||
their formatting. ReleaseKit currently leaves this generic mechanism to
|
||
consumer-owned additional checks. Shared support would remove that script
|
||
fragment and provide consistent diagnostics across applications.
|
||
|
||
### Target end state
|
||
|
||
An optional public API and profile selection enables formatting validation for
|
||
tracked Go source using ordinary `gofmt` conventions. `Check` and `Publish`,
|
||
including their CLI forms, apply the same check within candidate validation.
|
||
The check runs offline, reports affected paths, and leaves files unchanged.
|
||
|
||
Consumers select the capability once and rely on ReleaseKit for enumeration,
|
||
format checking, and failure reporting. Existing validation defaults remain
|
||
unchanged when the option is unset.
|
||
|
||
PromptKit can now remove its local formatting loop and select the shared check
|
||
through its release profile when it adopts the capability.
|
||
|
||
## 8. Offer offline Markdown-link validation
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
PromptKit's largest generic validation block is a local Markdown-link checker.
|
||
It owns parsing, destination resolution, heading anchors, and diagnostics.
|
||
ReleaseKit currently leaves these mechanics to consumer-owned additional checks.
|
||
|
||
Sharing the check would remove a locally maintained parser and give consumers
|
||
one documented convention for validating navigation within their documentation.
|
||
Consumers that require documentation to remain within the checkout also need
|
||
a shared option to enforce that boundary.
|
||
|
||
### Target end state
|
||
|
||
An optional public API and profile selection checks tracked Markdown documents
|
||
for local destinations and supported heading fragments within the checkout.
|
||
`Check` and `Publish`, including their CLI forms, use the same offline,
|
||
read-only validation and report the source file, location, and target of each
|
||
problem.
|
||
|
||
ReleaseKit owns a documented link and heading-anchor convention that consumers
|
||
can follow, using PromptKit's current conventions as the starting specification.
|
||
The supported behavior accounts for common inline and reference links, code
|
||
examples, escaped destinations, and duplicate headings. External
|
||
website availability is outside the check's scope.
|
||
|
||
By default, links outside the checkout are classified and reported as outside
|
||
the shared check's scope. An optional setting makes local destinations outside
|
||
the checkout a validation failure, using the same parser and diagnostics.
|
||
Boundary validation remains independent of neighboring checkout contents.
|
||
Existing validation defaults remain unchanged when the option is unset.
|
||
|
||
PromptKit can now replace its local Markdown checker with a profile selection
|
||
and rely on shared parsing rules and diagnostics when it adopts the capability.
|
||
|
||
## 9. Offer module-distribution checks
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
PromptKit checks that released source is independent of neighboring checkouts
|
||
by excluding committed workspace files and local filesystem module replacements.
|
||
ReleaseKit's offline Go environment controls validation execution; inspecting
|
||
the distributed candidate requires separate checks that consumers currently own.
|
||
|
||
Shared inspection would remove these local checks and provide consistent
|
||
diagnostics for consumers with the same distribution requirements.
|
||
|
||
### Target end state
|
||
|
||
The public API and profile offer independently selectable rules for committed
|
||
workspace files (`go.work` and `go.work.sum`) and local filesystem replacements
|
||
in committed module declarations. Each selected rule reports offending paths
|
||
and, where applicable, module directives through shared candidate validation.
|
||
|
||
The replacement rule permits versioned module replacements. Workspace use and
|
||
vendoring retain their existing behavior unless affected by a selected rule.
|
||
The checks inspect candidate contents independently of the Go test environment.
|
||
`Check` and `Publish`, including their CLI forms, apply the same offline,
|
||
read-only checks. Omitted selections preserve current defaults.
|
||
|
||
PromptKit can now declare its distribution requirements and remove the
|
||
corresponding consumer-owned checks when it adopts the selections.
|
||
|
||
## 10. Offer an individual-file-size check
|
||
|
||
### Rationale and baseline at plan start
|
||
|
||
Unintentionally committed binaries and large assets can increase the size of
|
||
released source. ReleaseKit currently leaves file-size inspection to consumers.
|
||
A shared check would catch oversized files while allowing each consumer to
|
||
declare its intended size limit and exceptions.
|
||
|
||
### Target end state
|
||
|
||
An optional public API and profile selection checks individual tracked files
|
||
in the current candidate. When enabled, the default limit is 1 MB (1,000,000
|
||
bytes); consumers can configure the limit and explicit repository-relative
|
||
path exclusions for intentional large files. A file exceeding the limit fails
|
||
validation with its path, observed size, and configured limit.
|
||
|
||
The check measures file size. Small binaries remain subject to ordinary review.
|
||
Its scope is the current candidate's files; historical objects and aggregate
|
||
repository size remain separate concerns. `Check` and `Publish`, including
|
||
their CLI forms, use the same offline, read-only inspection. The check is
|
||
disabled by default.
|
||
|
||
Consumers can now catch oversized candidate files through a small declaration
|
||
and remove corresponding local inspection code when they adopt the check.
|