diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index ef3abdb..47f4ddb 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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 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 no Go module, packages, executable, tests, or publication automation. The 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 requirements. -The six sibling checkouts are consumer evidence and future migration targets. -They are independent repositories. Their source and instructions must be -rechecked before each migration; the earlier line counts are historical review -measurements. Consult their code through the knowledge graph, indexing a -repository when necessary. Documents, scripts, and CI configuration may be read -directly under the discovery instructions. +The six sibling checkouts provide design evidence; this implementation sequence +changes ReleaseKit only. Consumer migrations and measurement of deleted consumer +infrastructure belong to later adoption work. Consult code through the knowledge +graph, indexing a repository when necessary. Documents, scripts, and CI +configuration may be read 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 @@ -39,7 +57,7 @@ directly under the discovery instructions. Add exported declarations as their behavior is implemented, with GoDoc. Implement the selected contract with proportionate internal collaborators. - 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 independent authority to strengthen the contract. - 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 consumer, CLI, configuration, integration, and internal documents when they have substantive content. Keep future behavior and stage progress here. -- Consumer migration stages change the named sibling repository as well as any - corresponding ReleaseKit examples. Follow that repository's policies, preserve - unrelated work, and commit each repository separately. When adding a runtime - dependency, update its module metadata and OSS attribution/companion license - texts in the same change using the actual selected source pin. A migration - needs a reachable immutable ReleaseKit pin, as described under Open Questions. -- Local implementation commits and tests against temporary remotes complete - stages. Real release publication, remote pushes, CI activation, and credential - provisioning require the maintainer's corresponding authorization. Do not - equate prepared integration with verified live delivery. +- Keep the implementation self-contained. Build the tool from this checkout; + temporary fixture modules may use local replacements. Integration templates + accept an operator-selected immutable tool pin for later deployment, without + requiring one to complete this plan or claiming that a release already exists. +- Complete stages with local implementation commits and controlled checks. + Prepare runnable automation and deployment instructions without activating + live workflows. Distinguish implemented integration from verified live use. + Finish the whole sequence before the maintainer's architecture review; add no + intermediate approval or external-action checkpoint. ## 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 strictly so unsupported build or delivery settings cannot silently disappear 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 `RELEASEKIT_GITEA_TOKEN`, only for delivery. Build receipt identity covers resolved 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 file hashes, selected filenames, and source/build-input identity before remote mutation. When no directory is supplied, build into a temporary directory from -the tagged checkout and then deliver. With zero targets, optional hosted delivery -creates a note page without a binary manifest. Neither mode reruns the candidate -test suite or changes source-publication status. +the tagged checkout and then deliver. With zero targets, hosted delivery creates +the required note page without a binary manifest or build receipt. An absent +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 @@ -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 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 -multipart attachment upload. Consult the host's schema during implementation; -record used operations in the integration guide. This observation is not an -all-version Gitea compatibility promise. +multipart attachment upload. Implement the operations described here against +local fixtures and record them in the integration guide. Verification against +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 `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 operator can rerun against the same tag and retained assets. -Woodpecker uses tag-triggered repository-local YAML with a pinned Go/tool image -and a pinned ReleaseKit source install. Provide an example using an official Go -image plus a separate provisioning step that installs ReleaseKit from its -immutable release pin and prepares consumer module caches. Build and deliver -then run with offline Go execution. This honors ReleaseKit's source-only initial -distribution; a dedicated ReleaseKit container image would require a separate -deliverable decision. Use the repository's selected Go toolchain image, which -must satisfy its own module requirements. +Woodpecker uses tag-triggered repository-local YAML with a pinned Go image +and an explicit tool preparation step. Provide source-only and binary-producing +examples. Consumer templates accept an operator-selected immutable ReleaseKit +source pin for deployment; template preparation and local execution use the +implementation checkout and require no published pin. Prepare consumer module +caches separately, then run builds and delivery with offline Go execution. +This honors ReleaseKit's source-only distribution; a dedicated ReleaseKit +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, -with an explicit tag fetch when the checkout omits local tag refs. The build step -writes to ignored `dist`; the delivery step shares the workspace and supplies -the Gitea token from a Woodpecker secret. Pin actual image digests and source -versions when adopting the example. Pipeline preparation may access dependency -services; candidate validation and builds use the prepared caches. CI does not -call `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. +with an explicit tag fetch when the checkout omits local tag refs. For binary +profiles, the build step writes to ignored `dist` and the delivery step shares +the workspace. Source-only workflows call delivery directly without an artifact +build step. Supply the Gitea token only to delivery from a Woodpecker secret. +Document operator substitution of image digests and source pins for eventual +consumer deployment. Pipeline preparation may access dependency services; +candidate validation and builds use the prepared caches. CI does not call +`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 @@ -616,50 +645,12 @@ Acceptance: source-only publication invokes no builder; selected build failure prevents tag creation; selected builds inject the exact candidate version; callback validation runs once. CLI artifacts and receipts agree on filenames, hashes, commit, and resolved build settings. Generated validation output does -not dirty the candidate. This completes the first source-publication/build -capability slice. +not dirty the candidate. Continue directly to hosted delivery implementation; +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. - -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. +Status: Pending. Depends on Stage 11. 1. Implement the small internal REST transport using the served API operations, 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 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 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 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 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 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. Bind source note, resolved build settings, tag commit, and hosted repository as specified. 2. Add delivery profile fields, environment-name token loading in the CLI, and `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 remote main equality. Verify receipt identity/hashes before supplied assets are used. Keep the library credential input explicit. 4. Add current consumer/CLI guidance for source status, delivery status, retained assets, and retry commands. Extend public boundary checks. -Acceptance: a facade/CLI end-to-end fixture builds tagged source and delivers to -a local server; a rerun is content-aware. Wrong commit, stale build settings or -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. +Acceptance: facade/CLI fixtures cover both page-only delivery and binary delivery +from tagged source to a local server, with content-aware reruns. Page-only +delivery preserves the complete note, needs no main package or receipt, and +performs no Go build or asset upload. Wrong commit, stale build settings or +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 - ReleaseKit source installation and cache preparation, artifact build, and - delivery with the configured secret. Explain how consumers pin their image - and tool source; create no new ReleaseKit image-distribution requirement. +1. Add maintained source-only and binary-producing tag-pipeline templates. + Parameterize the Go image and immutable ReleaseKit source pin for eventual + deployment, with explicit installation/cache preparation and a delivery + 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 necessary, share generated assets between steps, and keep output ignored. 3. Document preparation versus offline execution, asynchronous status, and - rerunning the same immutable tag. The workflow executes no publisher. -4. Exercise its shell command sequence locally against a fixture and local - server. Verify YAML with an available supported Woodpecker validator when - available; report that live runner behavior remains unverified otherwise. + rerunning the same immutable tag. The source-only template delivers the note + page directly; the binary template first builds its declared assets. Neither + workflow executes the publisher. +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 -the selected version and commit, and secrets enter only the delivery step. -Static/manual YAML review and local command evidence are recorded accurately. +Acceptance: the maintained commands reach common delivery for both profile types +and common builds for declared binary targets, with the selected version and +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 [Woodpecker environment reference](https://woodpecker-ci.org/docs/usage/environment) 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 - before configuration/provider initialization. Use graph discovery to locate - its CLI boundary; the earlier implementation has no release version command. -2. Set main package `./cmd/scriptorium`, binary name `scriptorium`, and its - existing Linux amd64/arm64 asset targets in the profile. -3. Replace the temporary local candidate build loop from Stage 13 with shared - candidate builds. Retain only product checks and a small version/wiring test. -4. Update current CLI contracts and compatibility impact documentation. +1. Extend ReleaseKit's source-only profile with its Gitea destination and token + environment name. Keep the build target set empty and retain its selected + offline candidate suite. No distributed executable or binary manifest is + introduced. +2. Prepare a repository-specific Woodpecker workflow under the maintained + examples, using the tagged checkout to build the local release tool and call + page-only delivery. Keep it outside active CI discovery during this sequence. + 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 -service access. The unchanged two-asset selection is used for candidate checks. -Runtime dependency checks show the application needs only `buildinfo` for this -responsibility; its ordinary suite passes. +Acceptance: ReleaseKit's source-only example creates a hosted page and accepts +an identical rerun without building consumer binaries, generating a manifest, +requiring a receipt, or consulting a previously released tool. Delivery failure +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 - common example adapted to its pinned Go/tool versions and Gitea destination. -2. Keep the committed note as the hosted body and maintain the existing two - Linux assets and checksum deliverable. Add ignored local build output. -3. Remove its repeated asset builder code once local fixture evidence exercises - common build and retry delivery. Update its delivery runbook and tests. +1. Map each initial capability in the feature roadmap to its implemented owner + and existing behavioral evidence. Record the concrete package and dependency + inventory, both supported facades, and their implemented responsibilities in + the canonical internal and consumer documentation. +2. Finish current API, CLI, configuration, integration, example, development, + 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, -partial delivery recovery, and conflicting bytes. The repository's source -publication path waits for no CI or attachments. Record live activation as a -separate maintainer action; preserve historical release workflows at old tags. - -## Stage 21: Migrate ConfigKit publication - -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 ` 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. +Acceptance: the initial library and executable provide check, publication, +build, runtime version access, page-only and binary delivery, partial/uncertain +recovery, and prepared Woodpecker integration. The documentation describes the +implemented boundary accurately. Completion depends on local implementation +and development evidence; architectural review, a broader testing plan, +consumer migrations, and release/deployment decisions follow this sequence. ## 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 | | Candidate capture, one validation, mutable guards | 5–8, 11 | | Authoritative endpoint and remote ref state | 6–8 | | 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 | | Native smoke, empty target sets, consistent names | 10–11 | -| Hosted page/note creation and immutable content | 14–17 | -| Full checksums, comparison, partial/additive retries | 15–17 | -| Woodpecker tag integration and separate statuses | 18, 20, 26, 29 | -| PromptKit and Scriptorium pilots | 12–13, 19–20 | -| ConfigKit, Notarius, Audita, Narratio adoption | 21–29 | -| Actual infrastructure reduction and canonical docs | 30 | +| Hosted page/note creation, including source-only projects | 12, 15, 17 | +| Full checksums, comparison, partial/additive retries | 13–15 | +| Prepared Woodpecker workflows for both delivery profiles | 16–17 | +| Complete initial implementation and canonical documentation | 18 | + +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 -The core implementation choices above are complete for the recommended design. -These maintainer decisions affect adoption and live use; do not fill in unknown -release pins or silently broaden deliverables. - -### Which immutable ReleaseKit versions should consumers pin? - -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. +None block this initial implementation sequence. The maintainer has selected +hosted pages for source-only projects and deferred pilots, releases, consumer +adoption, and broader testing decisions until after implementation and the +subsequent architecture review. Actual release pins and deployment credentials +are inputs to later adoption; no stage requires them. diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index eb7ce6b..8e0ae6f 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -141,14 +141,16 @@ source, using the same version and target selection. A common tag-triggered Woodpecker workflow can run ReleaseKit against the tagged source. Repository-local YAML should declare the pinned tool image and credentials; each repository's ReleaseKit configuration should declare its -main package and target set. ReleaseKit can own version injection, cross-builds, -checksum generation, and delivery. The source-only repositories can declare -zero binary assets. +delivery destination and any binary main package and target set. ReleaseKit can +own version injection, cross-builds, checksum generation, and delivery. All +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 -could create or find the release for the tag, use the checked-in note, and add -the declared assets and checksum manifest. A retry should inspect existing -assets, verify matching content, add only missing items, and stop on a conflict. +The shared delivery command should create or find the release for the tag, +use the checked-in note, and add declared binary assets and their checksum +manifest where applicable. A retry should inspect existing assets, verify +matching content, add only missing items, and stop on a conflict. An existing checksum manifest must remain consistent with any later addition. The release and its attachments are separate remote operations, so partial 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 the plugin's skip behavior. -Requiring a hosted Gitea release for PromptKit, ConfigKit, or Notarius would -add a deliverable and credentials to their current source-only policies. That -decision can be made separately from standardizing delivery for projects that -already publish hosted assets. +Hosted pages are selected for source-only projects, including PromptKit, +ConfigKit, Notarius, and ReleaseKit. Adoption adds a page deliverable and delivery +credentials to their procedures while preserving successful tag publication as +source completion. The initial implementation should support both page-only and +binary delivery through the same facade and command. ## 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`. Source-only libraries need no runtime import or automatic binary deliverable. 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. Consumer policy and procedure changes should describe the deliberately adopted standard and its compatibility impact. Adoption should demonstrate reduced local -infrastructure and one coherent release model. The implementation plan owns -pilot selection, migration order, and acceptance evidence. +infrastructure and one coherent release model. The implementation plan owns the +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