Focus the plan on the complete initial implementation
This commit is contained in:
@@ -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 <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.
|
||||
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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user