ReleaseKit/docs/roadmap/v0.2.0.md

# 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. Establish the shared validation API and profile model

### Rationale and current baseline

ReleaseKit has a shared candidate workflow and a product-specific additional
check extension point. The optional validation capabilities planned for v0.2.0
need a coherent selection and diagnostic model across the Go API and profile.

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.

### Work needed

- Design and integrate the shared specification, profile mapping, execution,
  and error model described in [model.md](model.md).
- Preserve existing default behavior and additional-check support, and align
  GoDoc, profile guidance, and CLI reporting as the model lands.
- Evaluate the model against Audita, ConfigKit, and PromptKit before finalizing
  the interfaces used by the individual validation features.

Completion should provide a common foundation for the validation capabilities
below, with small consumer declarations and reusable execution.

## 2. 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.

## 3. 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.

## 4. 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.

## 5. 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.

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.

### 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.

## 6. 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 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.

### 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.

## 7. 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.

## 8. 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.
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.

### 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.
- Add the optional checkout-boundary rule to the shared Markdown settings,
  with diagnostics that identify the source location and destination.
- Document supported behavior and verify valid and broken links, heading
  fragments, representative Markdown syntax, and handling of code examples
  and links outside the checkout with the boundary rule enabled and disabled.
- 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.

## 9. Offer module-distribution checks

### Rationale and current baseline

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.

### Work needed

- Add independent distribution-rule selections to the validation API and profile.
- Implement shared candidate-file inspection and module-declaration parsing,
  distinguishing local filesystem replacements from versioned replacements.
- Document the inspection scope and diagnostics, and verify workspace files,
  local and versioned replacements, and independent rule selection.
- Verify equivalent API/CLI behavior, unchanged defaults, and inspection of
  distributed files regardless of workspace discovery settings during testing.

Completion should let PromptKit declare its distribution requirements and
remove the corresponding consumer-owned checks.

## 10. Offer an individual-file-size check

### Rationale and current baseline

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.

### Work needed

- Add file-size selection, a configurable byte limit, and path exclusions to
  the shared validation API and profile.
- Implement candidate-file size inspection with actionable diagnostics.
- Document units, threshold behavior, exclusions, and the scope of inspection.
- Verify files below, at, and above the limit; configured limits and exclusions;
  and equivalent API/CLI behavior with the check enabled and disabled.

Completion should let consumers catch oversized candidate files through a
small declaration and remove any corresponding local inspection code.