eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Focus the plan on the complete initial implementation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-05 16:29:02 +00:00
parent 6c2695f870
commit cc7ca47469
2 changed files with 191 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files

521
docs/roadmap/implementation.md
View File

@@ -12,19 +12,37 @@ execution order, for the target state in the [feature roadmap](releasekit.md).
The roadmap owns product intent and selected release conventions. This document The roadmap owns product intent and selected release conventions. This document
owns implementation steps, dependencies, acceptance evidence, and progress. owns implementation steps, dependencies, acceptance evidence, and progress.
The baseline is ReleaseKit commit `43c20b0`. It contains documentation, adopted The baseline is ReleaseKit commit `6c2695f`. It contains documentation, adopted
policies, licensing notices, and [ADR 0001](../adr/0001-public-facade.md). It has policies, licensing notices, and [ADR 0001](../adr/0001-public-facade.md). It has
no Go module, packages, executable, tests, or publication automation. The no Go module, packages, executable, tests, or publication automation. The
worktree was clean when this plan was prepared. The available tools were Go worktree was clean when this plan was prepared. The available tools were Go
1.26.8 on linux/amd64 and Git 2.53.0; these observations are not minimum support 1.26.8 on linux/amd64 and Git 2.53.0; these observations are not minimum support
requirements. requirements.
The six sibling checkouts are consumer evidence and future migration targets. The six sibling checkouts provide design evidence; this implementation sequence
They are independent repositories. Their source and instructions must be changes ReleaseKit only. Consumer migrations and measurement of deleted consumer
rechecked before each migration; the earlier line counts are historical review infrastructure belong to later adoption work. Consult code through the knowledge
measurements. Consult their code through the knowledge graph, indexing a graph, indexing a repository when necessary. Documents, scripts, and CI
repository when necessary. Documents, scripts, and CI configuration may be read configuration may be read directly under the discovery instructions.
directly under the discovery instructions.
## Scope and completion
Deliver the complete initial library, executable, configuration, shared build
and delivery mechanics, Woodpecker examples, and ReleaseKit's own prepared
release wiring. Hosted Gitea release pages are part of the selected standard
for every project, including source-only projects. Source-only delivery uses
the committed release note and zero binary assets; it needs no binary build or
checksum manifest.
Proceed through all stages using the local checkout and controlled fixtures.
No stage depends on an intermediate release, published tool/runtime pin,
consumer pilot, external service action, or human review. Ordinary automated
development checks accompany implementation under the testing policy.
After the complete initial implementation, the maintainer will review the
architecture, address discovered issues, and then choose the broader testing
plan and next steps. Consumer adoption, live integration testing, secret
provisioning, CI activation, and actual publication are outside this sequence.
## Execution instructions ## Execution instructions
@@ -39,7 +57,7 @@ directly under the discovery instructions.
Add exported declarations as their behavior is implemented, with GoDoc. Add exported declarations as their behavior is implemented, with GoDoc.
Implement the selected contract with proportionate internal collaborators. Implement the selected contract with proportionate internal collaborators.
- The design choices below specify this draft's recommended implementation. - The design choices below specify this draft's recommended implementation.
They become implementation instructions when the plan is approved. Later Apply the selected scope and decisions throughout the sequence. Later
agent-authored code or tests provide evidence of implementation, rather than agent-authored code or tests provide evidence of implementation, rather than
independent authority to strengthen the contract. independent authority to strengthen the contract.
- For each stage, run focused behavioral checks for its changed risks and the - For each stage, run focused behavioral checks for its changed risks and the
@@ -53,16 +71,15 @@ directly under the discovery instructions.
- Update canonical documentation with each implemented responsibility. Create - Update canonical documentation with each implemented responsibility. Create
consumer, CLI, configuration, integration, and internal documents when they consumer, CLI, configuration, integration, and internal documents when they
have substantive content. Keep future behavior and stage progress here. have substantive content. Keep future behavior and stage progress here.
- Consumer migration stages change the named sibling repository as well as any - Keep the implementation self-contained. Build the tool from this checkout;
corresponding ReleaseKit examples. Follow that repository's policies, preserve temporary fixture modules may use local replacements. Integration templates
unrelated work, and commit each repository separately. When adding a runtime accept an operator-selected immutable tool pin for later deployment, without
dependency, update its module metadata and OSS attribution/companion license requiring one to complete this plan or claiming that a release already exists.
texts in the same change using the actual selected source pin. A migration - Complete stages with local implementation commits and controlled checks.
needs a reachable immutable ReleaseKit pin, as described under Open Questions. Prepare runnable automation and deployment instructions without activating
- Local implementation commits and tests against temporary remotes complete live workflows. Distinguish implemented integration from verified live use.
stages. Real release publication, remote pushes, CI activation, and credential Finish the whole sequence before the maintainer's architecture review; add no
provisioning require the maintainer's corresponding authorization. Do not intermediate approval or external-action checkpoint.
equate prepared integration with verified live delivery.
## Implementation decisions ## Implementation decisions
@@ -189,7 +206,9 @@ An absent or empty check list selects `go test -count=1 ./...`; a nonempty list
is the repository's complete validation sequence. Decode profile fields is the repository's complete validation sequence. Decode profile fields
strictly so unsupported build or delivery settings cannot silently disappear strictly so unsupported build or delivery settings cannot silently disappear
from the selected checks. Validate required values for the operation being run; from the selected checks. Validate required values for the operation being run;
a source-only profile needs neither a main package nor credentials. source-only checks and publication need neither a main package nor credentials.
Hosted page delivery requires a destination and token for source-only profiles
as well as binary-producing profiles.
The CLI loads the token named by `delivery.token_env`, defaulting to The CLI loads the token named by `delivery.token_env`, defaulting to
`RELEASEKIT_GITEA_TOKEN`, only for delivery. Build receipt identity covers resolved `RELEASEKIT_GITEA_TOKEN`, only for delivery. Build receipt identity covers resolved
build inputs; delivery credentials, destination, and unrelated check settings build inputs; delivery credentials, destination, and unrelated check settings
@@ -336,9 +355,10 @@ current remote `main` to remain at an old release commit during delivery retries
The CLI's `deliver --assets DIR` consumes a verified build receipt and checks The CLI's `deliver --assets DIR` consumes a verified build receipt and checks
file hashes, selected filenames, and source/build-input identity before remote file hashes, selected filenames, and source/build-input identity before remote
mutation. When no directory is supplied, build into a temporary directory from mutation. When no directory is supplied, build into a temporary directory from
the tagged checkout and then deliver. With zero targets, optional hosted delivery the tagged checkout and then deliver. With zero targets, hosted delivery creates
creates a note page without a binary manifest. Neither mode reruns the candidate the required note page without a binary manifest or build receipt. An absent
test suite or changes source-publication status. build specification is equivalent to zero targets for source-only delivery.
Neither mode reruns the candidate test suite or changes source-publication status.
### Hosted delivery and Woodpecker ### Hosted delivery and Woodpecker
@@ -346,9 +366,10 @@ Use a small internal standard-library Gitea REST client. On 2026-10-05 the host'
[version endpoint](https://gitea.maximumdirect.net/api/v1/version) reported Gitea [version endpoint](https://gitea.maximumdirect.net/api/v1/version) reported Gitea
1.25.4; its [served API schema](https://gitea.maximumdirect.net/swagger.v1.json) 1.25.4; its [served API schema](https://gitea.maximumdirect.net/swagger.v1.json)
confirmed release-by-tag lookup, JSON release creation, asset listing, and confirmed release-by-tag lookup, JSON release creation, asset listing, and
multipart attachment upload. Consult the host's schema during implementation; multipart attachment upload. Implement the operations described here against
record used operations in the integration guide. This observation is not an local fixtures and record them in the integration guide. Verification against
all-version Gitea compatibility promise. the deployed host belongs to later live testing and is not needed to complete
this sequence. This observation is not an all-version Gitea compatibility promise.
Read the tag through `/api/v1/repos/{owner}/{repo}/tags/{tag}` and verify its Read the tag through `/api/v1/repos/{owner}/{repo}/tags/{tag}` and verify its
`commit.sha`. Use the repository API prefix for each following operation. Find `commit.sha`. Use the repository API prefix for each following operation. Find
@@ -385,24 +406,32 @@ concurrent creation by finding and verifying the created resource. Do not
blindly retry writes or delete attachments. Record partial progress so an blindly retry writes or delete attachments. Record partial progress so an
operator can rerun against the same tag and retained assets. operator can rerun against the same tag and retained assets.
Woodpecker uses tag-triggered repository-local YAML with a pinned Go/tool image Woodpecker uses tag-triggered repository-local YAML with a pinned Go image
and a pinned ReleaseKit source install. Provide an example using an official Go and an explicit tool preparation step. Provide source-only and binary-producing
image plus a separate provisioning step that installs ReleaseKit from its examples. Consumer templates accept an operator-selected immutable ReleaseKit
immutable release pin and prepares consumer module caches. Build and deliver source pin for deployment; template preparation and local execution use the
then run with offline Go execution. This honors ReleaseKit's source-only initial implementation checkout and require no published pin. Prepare consumer module
distribution; a dedicated ReleaseKit container image would require a separate caches separately, then run builds and delivery with offline Go execution.
deliverable decision. Use the repository's selected Go toolchain image, which This honors ReleaseKit's source-only distribution; a dedicated ReleaseKit
must satisfy its own module requirements. container image would require a separate deliverable decision. Use a Go image
that satisfies the repository's module requirements.
ReleaseKit's own prepared workflow builds `cmd/releasekit` from its tagged
checkout using the local toolchain and delivers its hosted note page. It needs
no previously released executable and produces no distributed binary assets.
Prepare this workflow locally; activation belongs to the later next-step plan.
Use `CI_COMMIT_TAG` and `CI_COMMIT_SHA` to bind the workflow to tagged source, Use `CI_COMMIT_TAG` and `CI_COMMIT_SHA` to bind the workflow to tagged source,
with an explicit tag fetch when the checkout omits local tag refs. The build step with an explicit tag fetch when the checkout omits local tag refs. For binary
writes to ignored `dist`; the delivery step shares the workspace and supplies profiles, the build step writes to ignored `dist` and the delivery step shares
the Gitea token from a Woodpecker secret. Pin actual image digests and source the workspace. Source-only workflows call delivery directly without an artifact
versions when adopting the example. Pipeline preparation may access dependency build step. Supply the Gitea token only to delivery from a Woodpecker secret.
services; candidate validation and builds use the prepared caches. CI does not Document operator substitution of image digests and source pins for eventual
call `publish`, push refs, or gate source completion. The supported retry is a consumer deployment. Pipeline preparation may access dependency services;
rerun from the same tagged source with content comparison; reproducible bytes candidate validation and builds use the prepared caches. CI does not call
across arbitrary toolchains or elapsed time are not promised. `publish`, push refs, or gate source completion. The supported retry is a rerun
from the same tagged source with content comparison; reproducible bytes across
arbitrary toolchains or elapsed time are not promised.
## Stage 1: Establish the Go module and development baseline ## Stage 1: Establish the Go module and development baseline
@@ -616,50 +645,12 @@ Acceptance: source-only publication invokes no builder; selected build failure
prevents tag creation; selected builds inject the exact candidate version; prevents tag creation; selected builds inject the exact candidate version;
callback validation runs once. CLI artifacts and receipts agree on filenames, callback validation runs once. CLI artifacts and receipts agree on filenames,
hashes, commit, and resolved build settings. Generated validation output does hashes, commit, and resolved build settings. Generated validation output does
not dirty the candidate. This completes the first source-publication/build not dirty the candidate. Continue directly to hosted delivery implementation;
capability slice. no publication or consumer pilot is needed to complete this stage.
## Stage 12: Pilot publication in PromptKit ## Stage 12: Find and create Gitea release pages
Status: Pending. Depends on Stage 11 and a reachable immutable tool pin. Status: Pending. Depends on Stage 11.
1. Review PromptKit's current instructions, release policies, and entry scripts.
Add a source-only profile using its actual note display name, currently
`Promptkit`. Keep its application-specific consumer example checks and other
deliberately adopted candidate gates in its validation command.
2. Replace repeated release guards and tag publication with a short ReleaseKit
invocation. Move note identity validation to ReleaseKit; remove extra shared
note-section requirements only through the corresponding local policy change.
3. Update installation prerequisites, local release wiring tests, and maintainer
documentation. Retain no duplicate mandatory pre-check before publication.
Acceptance: isolated repository fixtures exercise the new wrapper and profile
against a local remote, preserve source-only behavior, and run the selected
candidate checker once. PromptKit's own suite passes. Record deleted shared
mechanics separately from retained product checks. No Go runtime dependency or
hosted page is introduced for this library.
## Stage 13: Pilot publication in Scriptorium
Status: Pending. Depends on Stage 12.
1. Adapt Scriptorium's publication entry point and release policy to the common
profile/command. Preserve its selected candidate test flags and genuinely
product-owned checks in a small local candidate command.
2. Retain its existing candidate build check temporarily: its application has
no canonical runtime version command yet. Document that shared builds are
deferred to Stage 19; the existing delivery pipeline continues meanwhile.
3. Transfer exact-object publication/failure tests into shared coverage and
retain a small wrapper/configuration test locally. Update its runbook.
Acceptance: local-remote fixtures confirm common publication and bounded
recovery without changing the existing asynchronous deliverables. Scriptorium's
own suite passes. The two pilots substantiate the same public facade with
different product checks and endpoint configurations.
## Stage 14: Find and create Gitea release pages
Status: Pending. Depends on Stage 13.
1. Implement the small internal REST transport using the served API operations, 1. Implement the small internal REST transport using the served API operations,
explicit destination/token inputs, context cancellation, and structured explicit destination/token inputs, context cancellation, and structured
@@ -679,9 +670,9 @@ wrong hosted tag prevents page creation. Existing historical titles are retained
when the body, tag, and release state match. Fixture assertions cover actual when the body, tag, and release state match. Fixture assertions cover actual
request paths, payloads, and authentication without using real credentials. request paths, payloads, and authentication without using real credentials.
## Stage 15: Inspect asset and manifest content ## Stage 13: Inspect asset and manifest content
Status: Pending. Depends on Stage 14. Status: Pending. Depends on Stage 12.
1. Generate the expected binary manifest from the declared build result. Add 1. Generate the expected binary manifest from the declared build result. Add
attachment discovery and streaming hash comparison of existing assets. attachment discovery and streaming hash comparison of existing assets.
@@ -696,9 +687,9 @@ different manifest is conflict; unreadable content is not treated as missing.
Source-only delivery generates no binary manifest. No write endpoint is used Source-only delivery generates no binary manifest. No write endpoint is used
by inspection tests. by inspection tests.
## Stage 16: Upload missing assets and report partial delivery ## Stage 14: Upload missing assets and report partial delivery
Status: Pending. Depends on Stage 15. Status: Pending. Depends on Stage 13.
1. Add multipart uploads for missing binaries in filename order, followed by a 1. Add multipart uploads for missing binaries in filename order, followed by a
missing manifest. Record completed work and pending asset identities. missing manifest. Record completed work and pending asset identities.
@@ -715,310 +706,140 @@ Acceptance: partial and unknown outcomes retain exact completed/pending facts;
retries do not overwrite or delete content; no blind repeat POST is made after retries do not overwrite or delete content; no blind repeat POST is made after
an ambiguous acknowledgment. Published manifest constraints hold across reruns. an ambiguous acknowledgment. Published manifest constraints hold across reruns.
## Stage 17: Expose tagged-source delivery through the facade and CLI ## Stage 15: Expose tagged-source delivery through the facade and CLI
Status: Pending. Depends on Stage 16. Status: Pending. Depends on Stage 14.
1. Implement `Deliver`, its facade-owned request/result values, and conversions. 1. Implement `Deliver`, its facade-owned request/result values, and conversions.
Bind source note, resolved build settings, tag commit, and hosted repository Bind source note, resolved build settings, tag commit, and hosted repository
as specified. as specified.
2. Add delivery profile fields, environment-name token loading in the CLI, and 2. Add delivery profile fields, environment-name token loading in the CLI, and
`deliver` with an optional verified assets directory. With no directory, `deliver` with an optional verified assets directory. With no directory,
build tagged-source artifacts in temporary storage before uploading. build declared tagged-source artifacts in temporary storage before uploading.
An absent build specification or empty target set selects page-only delivery:
skip the builder, native smoke, receipt requirement, and manifest generation.
3. Accept detached tagged checkouts and historical tags without requiring old 3. Accept detached tagged checkouts and historical tags without requiring old
remote main equality. Verify receipt identity/hashes before supplied assets remote main equality. Verify receipt identity/hashes before supplied assets
are used. Keep the library credential input explicit. are used. Keep the library credential input explicit.
4. Add current consumer/CLI guidance for source status, delivery status, 4. Add current consumer/CLI guidance for source status, delivery status,
retained assets, and retry commands. Extend public boundary checks. retained assets, and retry commands. Extend public boundary checks.
Acceptance: a facade/CLI end-to-end fixture builds tagged source and delivers to Acceptance: facade/CLI fixtures cover both page-only delivery and binary delivery
a local server; a rerun is content-aware. Wrong commit, stale build settings or from tagged source to a local server, with content-aware reruns. Page-only
receipt, tampered assets, and missing credentials prevent relevant writes. Candidate delivery preserves the complete note, needs no main package or receipt, and
tests and Git publication are not run by delivery. A delivery failure leaves performs no Go build or asset upload. Wrong commit, stale build settings or
the existing source tag intact and reports only delivery failure. receipt, tampered assets, and missing credentials prevent relevant writes.
Candidate tests and Git publication are not run by delivery. A delivery failure
leaves the existing source tag intact and reports only delivery failure.
## Stage 18: Provide the common Woodpecker integration ## Stage 16: Provide the common Woodpecker integration
Status: Pending. Depends on Stage 17 and the delivery-capable tool pin. Status: Pending. Depends on Stage 15.
1. Add a maintained example tag pipeline using a pinned Go image, explicit 1. Add maintained source-only and binary-producing tag-pipeline templates.
ReleaseKit source installation and cache preparation, artifact build, and Parameterize the Go image and immutable ReleaseKit source pin for eventual
delivery with the configured secret. Explain how consumers pin their image deployment, with explicit installation/cache preparation and a delivery
and tool source; create no new ReleaseKit image-distribution requirement. secret. Document required template inputs rather than inventing a published
pin. Create no new ReleaseKit image-distribution requirement.
2. Bind tag and commit variables to the checkout, fetch the selected tag when 2. Bind tag and commit variables to the checkout, fetch the selected tag when
necessary, share generated assets between steps, and keep output ignored. necessary, share generated assets between steps, and keep output ignored.
3. Document preparation versus offline execution, asynchronous status, and 3. Document preparation versus offline execution, asynchronous status, and
rerunning the same immutable tag. The workflow executes no publisher. rerunning the same immutable tag. The source-only template delivers the note
4. Exercise its shell command sequence locally against a fixture and local page directly; the binary template first builds its declared assets. Neither
server. Verify YAML with an available supported Woodpecker validator when workflow executes the publisher.
available; report that live runner behavior remains unverified otherwise. 4. Exercise both command sequences locally with a tool built from this checkout,
fixture repositories, and a local server. Substitute the local executable for
the templates' installation step during development checks. Check YAML using
locally available tooling or static inspection; no live runner or new
external validator is needed to complete the stage.
Acceptance: the maintained commands reach common build/delivery operations with Acceptance: the maintained commands reach common delivery for both profile types
the selected version and commit, and secrets enter only the delivery step. and common builds for declared binary targets, with the selected version and
Static/manual YAML review and local command evidence are recorded accurately. commit. Secrets enter only the delivery step. Agent-performed static YAML checks
and local command evidence are recorded accurately. No published tool pin,
container pull, configured secret, or live runner is a stage prerequisite.
CI success is not a source release gate. The CI success is not a source release gate. The
[Woodpecker environment reference](https://woodpecker-ci.org/docs/usage/environment) [Woodpecker environment reference](https://woodpecker-ci.org/docs/usage/environment)
owns the runner-provided tag and commit variables. owns the runner-provided tag and commit variables.
## Stage 19: Standardize Scriptorium runtime information and builds ## Stage 17: Prepare ReleaseKit's own hosted-page delivery
Status: Pending. Depends on Stage 18 and a released runtime dependency pin. Status: Pending. Depends on Stage 16.
1. Add the `buildinfo` dependency and canonical `scriptorium version` command 1. Extend ReleaseKit's source-only profile with its Gitea destination and token
before configuration/provider initialization. Use graph discovery to locate environment name. Keep the build target set empty and retain its selected
its CLI boundary; the earlier implementation has no release version command. offline candidate suite. No distributed executable or binary manifest is
2. Set main package `./cmd/scriptorium`, binary name `scriptorium`, and its introduced.
existing Linux amd64/arm64 asset targets in the profile. 2. Prepare a repository-specific Woodpecker workflow under the maintained
3. Replace the temporary local candidate build loop from Stage 13 with shared examples, using the tagged checkout to build the local release tool and call
candidate builds. Retain only product checks and a small version/wiring test. page-only delivery. Keep it outside active CI discovery during this sequence.
4. Update current CLI contracts and compatibility impact documentation. Document where to place it for later activation and how to supply its secret.
3. Update the release policy's deliverable declaration and `docs/release.md`
together to identify the hosted note page, automation responsibility, and
page-delivery retry command. Source completion remains the exact tag push.
4. Exercise the prepared command sequence against a temporary tagged repository
and local HTTP server. Retain the note's complete body, including licensing
footer, on the hosted page.
Acceptance: shared builds report the injected version without credentials or Acceptance: ReleaseKit's source-only example creates a hosted page and accepts
service access. The unchanged two-asset selection is used for candidate checks. an identical rerun without building consumer binaries, generating a manifest,
Runtime dependency checks show the application needs only `buildinfo` for this requiring a receipt, or consulting a previously released tool. Delivery failure
responsibility; its ordinary suite passes. leaves source status unchanged. Workflow preparation requires no real tag,
credentials, remote push, CI activation, or maintainer checkpoint.
## Stage 20: Pilot common delivery in Scriptorium ## Stage 18: Complete the initial implementation and handoff documentation
Status: Pending. Depends on Stage 19. Status: Pending. Depends on Stage 17.
1. Replace its duplicated Woodpecker build loop and release-plugin step with the 1. Map each initial capability in the feature roadmap to its implemented owner
common example adapted to its pinned Go/tool versions and Gitea destination. and existing behavioral evidence. Record the concrete package and dependency
2. Keep the committed note as the hosted body and maintain the existing two inventory, both supported facades, and their implemented responsibilities in
Linux assets and checksum deliverable. Add ignored local build output. the canonical internal and consumer documentation.
3. Remove its repeated asset builder code once local fixture evidence exercises 2. Finish current API, CLI, configuration, integration, example, development,
common build and retry delivery. Update its delivery runbook and tests. and release documentation. Check links and consistency with actual behavior;
keep licensing and attribution accurate for incorporated material.
3. Run the established offline default suite and relevant existing boundary
checks for the assembled implementation. Resolve implementation defects
within this scope without adding a new permanent release matrix or live
testing requirement.
4. Record the completed initial implementation and evidence in this plan.
Identify prepared integrations whose live operation remains unverified and
hand off the implementation for the maintainer's subsequent architecture
review. Keep consumer migrations and their anticipated code savings marked
as future adoption work.
Acceptance: local fixture execution verifies first delivery, matching rerun, Acceptance: the initial library and executable provide check, publication,
partial delivery recovery, and conflicting bytes. The repository's source build, runtime version access, page-only and binary delivery, partial/uncertain
publication path waits for no CI or attachments. Record live activation as a recovery, and prepared Woodpecker integration. The documentation describes the
separate maintainer action; preserve historical release workflows at old tags. implemented boundary accurately. Completion depends on local implementation
and development evidence; architectural review, a broader testing plan,
## Stage 21: Migrate ConfigKit publication consumer migrations, and release/deployment decisions follow this sequence.
Status: Pending. Depends on Stage 20.
1. Add a source-only profile and wrapper using the common publisher. Its current
sequential main/tag publication becomes main-first preparation and tag-only
publication. Update the adopted policy and maintainer runbook together.
2. Preserve its existing selected baseline-toolchain, test, vet, and build
checks in its candidate checker where its local policy justifies them.
These remain ConfigKit checks, not ReleaseKit-wide requirements.
3. Remove duplicated ref checks, annotated-tag creation, and push recovery.
Retain a small profile/wrapper test and run its suite.
Acceptance: a local fixture refuses publication until authoritative main equals
the candidate, then publishes only the tag with one candidate-check invocation.
ConfigKit gains no runtime import, hosted page, or distributed binary.
## Stage 22: Migrate Notarius publication
Status: Pending. Depends on Stage 21.
1. Add a source-only profile and common publication wrapper. Its existing
branch push and lightweight tag become prepared main plus annotated tag.
Update the adopted policy and procedure with that deliberate change.
2. Retain its existing explicit host version check temporarily in its local
checker. Remove repeated common release guards and shared publication tests.
3. Preserve a small wrapper/check invocation test and verify ordinary behavior.
Acceptance: local remotes demonstrate the new publication approach and bounded
recovery. Source-only deliverables and the current version-check prerequisite
remain unchanged until the next stage.
## Stage 23: Standardize Notarius runtime version access
Status: Pending. Depends on Stage 22 and a released runtime dependency pin.
1. Replace its private override/resolution mechanism with `buildinfo`. Preserve
its existing `--version` invocation and add the canonical `version` command
for common smoke checks, with `notarius <version>` output.
2. Document the common metadata/`dev` fallback and its deliberate effect on any
existing unversioned-build diagnostic behavior. Update owned tests/contracts
rather than silently preserving obsolete private override assumptions.
3. Replace the explicit host check's private linker flags with a small local
invocation of the shared Build API for the host target. This remains an
explicitly selected local check, not a distributed target declaration.
The API accepts explicit host Go targets as described above.
Acceptance: both version invocations report the same injected value without
configuration or credentials, and the deliberate source-build behavior is
covered. The source-only profile still has no automatic binary targets or Gitea
page; the separately selected host check runs once with its candidate checker.
## Stage 24: Migrate Audita publication
Status: Pending. Depends on Stage 23.
1. Replace atomic main/tag publication with main-first preparation and the
common annotated-tag publisher. Retain its `--check` user entry by mapping it
to common local `check`; map `--publish` to common publication.
2. Preserve current tests and its existing builder temporarily as selected
candidate checks. Update the local release policy and completion wording.
3. Transfer shared atomic/lightweight publication tests to the common contract,
retaining tests of the Audita command mapping and local checks.
Acceptance: diagnostic mode performs no remote publication; publication refuses
an unprepared main and uses an annotated tag. The configured candidate sequence
runs once and existing asynchronous Linux deliverables remain selected.
## Stage 25: Standardize Audita runtime information and builds
Status: Pending. Depends on Stage 24 and a released runtime dependency pin.
1. Add `audita version` using `buildinfo`, before application configuration and
provider initialization. The earlier CLI has no release-version accessor.
2. Declare `./cmd/audita`, binary name `audita`, and linux/amd64 plus linux/arm64.
Replace `scripts/build-release.sh` mechanics with shared candidate/build
operations and retain product-owned tests.
3. Add a small application version-command test and update current contracts.
Acceptance: native smoke verifies the injected tag and needs no credentials;
both existing Linux assets retain their names/target selection. Audita's own
suite passes and duplicate candidate build work is removed.
## Stage 26: Migrate Audita delivery
Status: Pending. Depends on Stage 25.
1. Adapt the common tag workflow to Audita's pinned image/tool, Gitea repository,
and secret name. Replace release-plugin skip-by-name behavior with shared
content verification and additive delivery.
2. Update delivery/retry documentation and remove unused build wrapper code.
Acceptance: local first-run, rerun, conflicting-content, and partial-delivery
fixtures exercise the actual configured filenames and complete manifest. Source
completion and live activation remain separate from delivery verification.
## Stage 27: Migrate Narratio publication
Status: Pending. Depends on Stage 26.
1. Retain main-first preparation and replace lightweight tags with common
annotated publication. Adapt its candidate checker and release entry point,
keeping its selected product checks and build mechanics temporarily.
2. Update policy/runbook and retire common version/note/ref helpers where their
behavior is now shared. Preserve remaining helper uses until Stage 28.
Acceptance: local publication fixtures cover exact candidate/tag identity and
common recovery; the checker runs once. Narratio retains its three declared
asset targets and existing delivery pipeline until subsequent stages.
## Stage 28: Standardize Narratio runtime information and builds
Status: Pending. Depends on Stage 27 and a released runtime dependency pin.
1. Replace its private buildinfo variable with the facade in its existing
`narratio version` command. Preserve output shape and update tests to use
supported behavior rather than mutating a private version variable.
2. Declare `./cmd/narratio`, binary name `narratio`, and linux/amd64,
linux/arm64, darwin/arm64. Use the prepared toolchain required by its module.
3. Replace `build-release-assets.sh` flags, host smoke, and target loop with
shared builds. Remove duplicate build invocation from its candidate checker.
Preserve product checks and remove helpers that now have no remaining use.
Acceptance: the native version probe and all three cross-builds pass; foreign
platform compilation is reported without a native-execution claim. A nonempty
caller output directory can retain unrelated files, and no broad recursive
cleanup is inherited from the former builder.
## Stage 29: Migrate Narratio delivery
Status: Pending. Depends on Stage 28.
1. Replace its release plugin and repeated tag-pipeline candidate validation
with the common prepared build/delivery workflow. Candidate validation belongs
to source publication; tagged delivery does not repeat it as a gate.
2. Keep its three binary assets, committed note, Gitea destination, and complete
checksum manifest. Adapt pinned images and tool versions to its Go baseline.
3. Update retry documentation and small repository-local integration checks.
Acceptance: fixture workflow evidence verifies all three filenames, full
manifest, matching rerun, and partial/ambiguous delivery. Existing historical
tags/pages/assets are untouched and source publication waits for no delivery.
## Stage 30: Audit the completed target state and documentation
Status: Pending. Depends on Stage 29.
1. Map each feature-roadmap responsibility to its implemented owner and tests.
Verify both public facades, source-only behavior, candidate checks, exact
publication, runtime injection, selected targets, hosted content verification,
partial recovery, and Woodpecker integration against current source.
2. Review the six migrations against both architecture success criteria: shared
infrastructure was removed and one coherent model was adopted. Count actual
removed scripts/tests, retained product checks, and new ReleaseKit code
separately; do not present the historical estimate as measured savings.
3. Check current documentation owners, links, examples, dependency attribution,
license texts, and maintainer runbooks. Record live integration verification
separately from local acceptance, including anything awaiting activation.
4. Update feature status and this plan from evidence. Retire completed execution
details during release preparation while preserving target intent, deferred
decisions, and useful navigation.
Acceptance: each roadmap responsibility has direct source and behavioral
evidence, each migrated repository retains only justified product checks and
small wiring coverage, and no unimplemented or unverified responsibility is
marked complete. Run affected suites according to their policies; add no new
permanent release matrix or synchronization gate.
## Coverage of the feature roadmap ## Coverage of the feature roadmap
| Target responsibility | Implementing stages | | Initial target responsibility | Implementing stages |
| --- | --- | | --- | --- |
| Two public facades and small runtime dependencies | 1–3, extended in 10–11 and 17 | | Two public facades and small runtime dependencies | 1–3, extended in 10–11 and 15 |
| Stable version and committed note identity | 5 | | Stable version and committed note identity | 5 |
| Candidate capture, one validation, mutable guards | 5–8, 11 | | Candidate capture, one validation, mutable guards | 5–8, 11 |
| Authoritative endpoint and remote ref state | 6–8 | | Authoritative endpoint and remote ref state | 6–8 |
| Annotated object publication and failure recovery | 7–9 | | Annotated object publication and failure recovery | 7–9 |
| ReleaseKit source-only bootstrap/runbook | 9 | | ReleaseKit source-only bootstrap/runbook | 9, 17 |
| Shared version injection and selected cross-builds | 2, 10–11 | | Shared version injection and selected cross-builds | 2, 10–11 |
| Native smoke, empty target sets, consistent names | 10–11 | | Native smoke, empty target sets, consistent names | 10–11 |
| Hosted page/note creation and immutable content | 14–17 | | Hosted page/note creation, including source-only projects | 12, 15, 17 |
| Full checksums, comparison, partial/additive retries | 15–17 | | Full checksums, comparison, partial/additive retries | 13–15 |
| Woodpecker tag integration and separate statuses | 18, 20, 26, 29 | | Prepared Woodpecker workflows for both delivery profiles | 16–17 |
| PromptKit and Scriptorium pilots | 12–13, 19–20 | | Complete initial implementation and canonical documentation | 18 |
| ConfigKit, Notarius, Audita, Narratio adoption | 21–29 |
| Actual infrastructure reduction and canonical docs | 30 | Consumer infrastructure reduction and convergence on the shared standard remain
feature-roadmap adoption goals. Their migration sequence, real-world testing,
and measured savings will be determined after the initial architecture review.
## Open Questions ## Open Questions
The core implementation choices above are complete for the recommended design. None block this initial implementation sequence. The maintainer has selected
These maintainer decisions affect adoption and live use; do not fill in unknown hosted pages for source-only projects and deferred pilots, releases, consumer
release pins or silently broaden deliverables. adoption, and broader testing decisions until after implementation and the
subsequent architecture review. Actual release pins and deployment credentials
### Which immutable ReleaseKit versions should consumers pin? are inputs to later adoption; no stage requires them.
Required before Stage 12, and refreshed before Stage 18 and runtime migrations.
**Recommended:** publish a first source release such as `v0.1.0` after Stage 11,
then a delivery-capable source release after Stage 17. Verify version availability
at preparation time and use the actual published pins in profiles' accompanying
installation instructions, CI provisioning, and application module dependencies.
This gives the publication pilots an early usable tool and lets later delivery
and runtime adopters depend on documented versioned contracts. Publication is a
separate maintainer-authorized action under the release policy.
**Viable alternative:** make immutable source-commit/pseudo-version pins available
for the pilots and publish the first numbered release after Stage 17. This
supports integration feedback before a numbered release, at the cost of more
operator bookkeeping and less friendly installation instructions. Neither
approach commits local checkout replacements or claims an unpublished version
exists. Record the selected pins here before dependent migration stages proceed.
### Should source-only projects also receive hosted Gitea release pages?
This decision is required only if adopting pages for PromptKit, ConfigKit,
Notarius, or ReleaseKit; their current plan stages preserve source-only delivery
without hosted-page requirements.
**Recommended:** retain their existing delivery scope initially. Support explicit
zero-asset hosted delivery in ReleaseKit, while using the three existing binary
publishers to establish its behavior. This meets the requested standardization
without adding credentials, CI operations, or a new deliverable to other projects.
**Viable alternative:** declare a hosted note page for every project, with zero
binary assets where appropriate. This gives uniform forge presentation and uses
the same delivery API, but needs deliberate local release-policy changes,
credentials, and responsibility for retries. If selected, add a small adoption
stage for each affected project before completing Stage 30.

34
docs/roadmap/releasekit.md
View File

@@ -141,14 +141,16 @@ source, using the same version and target selection.
A common tag-triggered Woodpecker workflow can run ReleaseKit against the A common tag-triggered Woodpecker workflow can run ReleaseKit against the
tagged source. Repository-local YAML should declare the pinned tool image and tagged source. Repository-local YAML should declare the pinned tool image and
credentials; each repository's ReleaseKit configuration should declare its credentials; each repository's ReleaseKit configuration should declare its
main package and target set. ReleaseKit can own version injection, cross-builds, delivery destination and any binary main package and target set. ReleaseKit can
checksum generation, and delivery. The source-only repositories can declare own version injection, cross-builds, checksum generation, and delivery. All
zero binary assets. projects should receive hosted Gitea
release pages. Source-only repositories declare zero binary assets and deliver
the committed release note without a binary build or checksum manifest.
For projects that declare a hosted Gitea release, a shared delivery command The shared delivery command should create or find the release for the tag,
could create or find the release for the tag, use the checked-in note, and add use the checked-in note, and add declared binary assets and their checksum
the declared assets and checksum manifest. A retry should inspect existing manifest where applicable. A retry should inspect existing assets, verify
assets, verify matching content, add only missing items, and stop on a conflict. matching content, add only missing items, and stop on a conflict.
An existing checksum manifest must remain consistent with any later addition. An existing checksum manifest must remain consistent with any later addition.
The release and its attachments are separate remote operations, so partial The release and its attachments are separate remote operations, so partial
delivery must be expected and reported clearly. delivery must be expected and reported clearly.
@@ -160,10 +162,11 @@ same bytes as a previously published file. Content comparison would be a
reason to implement a shared Gitea delivery client rather than rely solely on reason to implement a shared Gitea delivery client rather than rely solely on
the plugin's skip behavior. the plugin's skip behavior.
Requiring a hosted Gitea release for PromptKit, ConfigKit, or Notarius would Hosted pages are selected for source-only projects, including PromptKit,
add a deliverable and credentials to their current source-only policies. That ConfigKit, Notarius, and ReleaseKit. Adoption adds a page deliverable and delivery
decision can be made separately from standardizing delivery for projects that credentials to their procedures while preserving successful tag publication as
already publish hosted assets. source completion. The initial implementation should support both page-only and
binary delivery through the same facade and command.
## Failure states ## Failure states
@@ -187,13 +190,16 @@ or checks. Shared mechanics and their repeated tests belong in ReleaseKit.
Application runtime code should obtain version information through `buildinfo`. Application runtime code should obtain version information through `buildinfo`.
Source-only libraries need no runtime import or automatic binary deliverable. Source-only libraries need no runtime import or automatic binary deliverable.
Projects declaring binaries should use the common target selection and version Projects declaring binaries should use the common target selection and version
injection; projects declaring hosted delivery should use content-aware retries. injection; hosted delivery should use content-aware retries for both page-only
and binary releases.
Existing published tags, notes, pages, and assets retain their historical contents. Existing published tags, notes, pages, and assets retain their historical contents.
Consumer policy and procedure changes should describe the deliberately adopted Consumer policy and procedure changes should describe the deliberately adopted
standard and its compatibility impact. Adoption should demonstrate reduced local standard and its compatibility impact. Adoption should demonstrate reduced local
infrastructure and one coherent release model. The implementation plan owns infrastructure and one coherent release model. The implementation plan owns the
pilot selection, migration order, and acceptance evidence. complete initial ReleaseKit implementation and its development evidence.
Architecture review follows that implementation; broader testing and consumer
migration steps will be chosen afterward.
## Reviewed implementations ## Reviewed implementations