276 lines
13 KiB
Markdown
276 lines
13 KiB
Markdown
# ReleaseKit v0.2.0 roadmap
|
|
|
|
Status: Draft scope for the next release.
|
|
|
|
This roadmap catalogs improvements to ReleaseKit v0.1.0. Each item records its
|
|
rationale, target state, and scope of work. A staged implementation plan will
|
|
follow once the release scope is finalized.
|
|
|
|
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. Use the application's module-selected ReleaseKit version in CI
|
|
|
|
### Rationale and current baseline
|
|
|
|
The maintained [CI template](../../examples/woodpecker/tag-delivery.yml) selects
|
|
ReleaseKit through a separate `RELEASEKIT_VERSION` value and invokes its command
|
|
with an explicit `@version`. The [adoption guidance](../consumers/delivery.md#woodpecker-tag-workflows)
|
|
instructs consumers to maintain that workflow pin.
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|
|
### Work needed
|
|
|
|
- Revise the maintained CI template to establish the tagged checkout before
|
|
selecting and building the module's ReleaseKit command. Remove the separate
|
|
version setting from this module-based integration and keep bootstrap logic
|
|
small and reusable.
|
|
- Update adoption and upgrade guidance to explain module-based selection,
|
|
compatible Go environments, dependency preparation, and migration from the
|
|
existing workflow pin. Explain the applicable bootstrap for consumers that
|
|
use a separately installed tool.
|
|
- Adapt workflow verification to exercise tool selection from the tagged
|
|
module configuration, including a dependency-version change, while preserving
|
|
tag/commit checks and existing source-only and binary delivery behavior.
|
|
- Apply the revised integration to Audita as the first consumer migration and
|
|
confirm that its local wrapper and CI use the same module-selected tool.
|
|
|
|
Completion should leave downstream maintainers with one ReleaseKit dependency
|
|
update for this integration and a maintained template they can adopt directly.
|
|
|
|
## 2. Select one base test invocation, including race testing
|
|
|
|
### Rationale and current baseline
|
|
|
|
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.
|
|
|
|
### Work needed
|
|
|
|
- Add compact validation options to the facade and profile, and carry them
|
|
through both candidate-check and publication paths.
|
|
- Extend shared Go invocation handling to apply race selection to the base
|
|
suite while preserving its offline environment and native test behavior.
|
|
- Update consumer guidance and verify default behavior, one selected suite run,
|
|
consistent API/CLI behavior, and propagation of validation failures.
|
|
|
|
Completion should let ConfigKit and PromptKit select a race-enabled suite once
|
|
and remove the corresponding consumer-owned test invocation.
|
|
|
|
## 3. Offer a separate full vet pass
|
|
|
|
### Rationale and current baseline
|
|
|
|
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.
|
|
|
|
### Work needed
|
|
|
|
- Add the full-vet selection to shared validation configuration and execution.
|
|
- Coordinate the base test invocation with the separate pass so consumers
|
|
express the desired coverage once.
|
|
- Document the selection and verify ordering, test-time vet omission, failure
|
|
handling, and unchanged default behavior through the shared validation path.
|
|
|
|
Completion should replace ConfigKit's and PromptKit's separate vet commands and
|
|
manual test-time vet settings with one declarative choice.
|
|
|
|
## 4. Verify package compilation for selected targets
|
|
|
|
### Rationale and current baseline
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Work needed
|
|
|
|
- Add a package-compilation target declaration to validation configuration,
|
|
distinct from the existing artifact build specification.
|
|
- Reuse internal Go environment and target handling for offline compilation,
|
|
replacing consumer-owned loops and preserving one base test execution.
|
|
- Document the distinction between compatibility checks and deliverables, and
|
|
verify selected-target compilation, failure reporting, and unchanged
|
|
source-only delivery behavior.
|
|
|
|
Completion should let ConfigKit declare its two Linux targets and remove its
|
|
release-specific compilation loop.
|
|
|
|
## 5. Check an optional expected publication endpoint
|
|
|
|
### Rationale and current baseline
|
|
|
|
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 with the resolved push endpoint 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.
|
|
|
|
### Work needed
|
|
|
|
- Add the optional expectation to the facade and profile and compare it at
|
|
the existing publication endpoint-resolution boundary.
|
|
- Reuse captured-endpoint handling and define the destination-comparison
|
|
semantics in GoDoc and consumer guidance.
|
|
- Verify matching, mismatching, and omitted expectations, including resolved
|
|
Git URL behavior, while preserving existing recheck and recovery coverage.
|
|
|
|
Completion should let consumers declare the intended push destination without
|
|
maintaining their own publication preflight logic.
|
|
|
|
## 6. Offer Go formatting validation
|
|
|
|
### Rationale and current baseline
|
|
|
|
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.
|
|
|
|
### Work needed
|
|
|
|
- Add formatting selection and shared inspection of tracked Go source to the
|
|
candidate-validation API, profile, and execution path.
|
|
- Provide actionable diagnostics for formatting differences and inspection
|
|
failures while preserving source files.
|
|
- Document the formatting convention and verify formatted and unformatted
|
|
inputs, consistent API/CLI behavior, and unchanged default validation.
|
|
|
|
Completion should let PromptKit remove its local formatting loop and select
|
|
the shared check through its release profile.
|
|
|
|
## 7. Offer offline Markdown-link validation
|
|
|
|
### Rationale and current baseline
|
|
|
|
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.
|
|
|
|
### 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. 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.
|
|
|
|
Links outside the checkout are classified and reported as outside the shared
|
|
check's scope. Validation remains independent of neighboring checkouts;
|
|
consumer-specific restrictions on those links remain additional product checks.
|
|
Existing validation defaults remain unchanged when the option is unset.
|
|
|
|
### Work needed
|
|
|
|
- Define the supported Markdown link forms and heading-anchor convention,
|
|
including destination resolution and diagnostics for out-of-scope links.
|
|
- Add shared parsing and local destination/fragment validation behind the
|
|
public validation API and profile selection.
|
|
- Document supported behavior and verify valid and broken links, heading
|
|
fragments, representative Markdown syntax, and handling of code examples
|
|
and links outside the checkout.
|
|
- Verify that checking is offline, preserves files, and behaves consistently
|
|
through candidate checking and publication.
|
|
|
|
Completion should let PromptKit replace its local Markdown checker with a
|
|
profile selection and rely on shared parsing rules and diagnostics.
|