diff --git a/README.md b/README.md index 45f320d..d327960 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ process. The Go module, root `releasekit` facade, `buildinfo` runtime package, local candidate check, source-tag publication API, selected-target build API, tagged-source delivery API, and `version`, `check`, `publish`, `build`, and `deliver` commands are implemented. ReleaseKit's source-only maintainer -procedure is documented. Its own hosted-page wiring and executable artifacts -remain future work. The +procedure and prepared Woodpecker workflow for hosted note-page delivery are +documented. ReleaseKit does not declare binary deliverables. The [product roadmap](docs/roadmap/releasekit.md) and [implementation plan](docs/roadmap/implementation.md) describe their selected behavior and sequence. @@ -41,8 +41,8 @@ failure recovery. ## Documentation -- [ReleaseKit proposal](docs/roadmap/releasekit.md): proposed publication, builds, - version injection, and delivery, with the initial implementation plan. +- [ReleaseKit proposal](docs/roadmap/releasekit.md): selected publication, builds, + version injection, and delivery conventions, with the implementation plan. - [Contributor guide](docs/development.md): orientation, validation, and selective policy reading. - [CLI contract](docs/cli.md): the `version`, `check`, `publish`, `build`, and diff --git a/docs/config.md b/docs/config.md index 015879b..6acae64 100644 --- a/docs/config.md +++ b/docs/config.md @@ -43,7 +43,7 @@ builds selected tagged-source targets into temporary storage or loads verified assets from the directory selected by `--assets`. An absent build object or an empty target set selects page-only delivery. -ReleaseKit's source-only publication profile is +ReleaseKit's source-only profile is [releasekit.json](../releasekit.json). See the [source-only profile](../examples/releasekit.json) and [binary profile](../examples/releasekit-binary.json). The diff --git a/docs/development.md b/docs/development.md index 90caeb7..ea7dab7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -69,5 +69,6 @@ Run the source publication command from the candidate repository root with `./scripts/release VERSION`. It uses the local Go toolchain and committed `releasekit.json` profile; prepare module dependencies before offline candidate validation. The [maintainer release procedure](release.md) owns preparation, -publication, and recovery. Executable artifacts and delivery remain outside -ReleaseKit's initial source-only release. +publication, and recovery. Hosted note-page delivery is a separate prepared +workflow and does not change the successful-tag-push completion point. ReleaseKit +does not declare binary deliverables. diff --git a/docs/internal/overview.md b/docs/internal/overview.md index dfb96ad..0e904d7 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -1,40 +1,82 @@ -# Internal package inventory +# Package and capability inventory -Public facades and their contracts are defined in Go declarations and GoDoc. -The [runtime consumer guide](../consumers/runtime-version.md) covers application -usage, and the [CLI contract](../cli.md) covers command behavior. +Public Go contracts are defined in declarations and GoDoc. ReleaseKit supports +two Go facades and a command-line interface: -Implemented internal packages: +- The root `releasekit` package is the orchestration facade. `Check` validates + one local candidate, `Publish` validates and publishes its exact annotated + source tag, `Build` compiles selected application targets, and `Deliver` + delivers a tagged note page and any declared assets. +- `buildinfo` is the small runtime facade. `Version` reports the injected + application version, the main-module version when available, or `dev`. +- `cmd/releasekit` is the executable interface. Its `version`, `check`, + `publish`, `build`, and `deliver` commands adapt profiles and command output + to the supported library operations. -- `internal/runtimeinfo` holds the injected version value and selects the - executable's main-module version when no injected value is present. -- `internal/versioncontract` names the linker symbol and stable version form - shared with the build and candidate operations. -- `internal/apicheck` checks compiled exports with `go/types` and checks import - direction. Run it with `go run ./internal/apicheck` from the repository root. -- `internal/process` runs cancellable child commands with per-child environment - overlays. -- `internal/build` compiles explicit Go targets with shared version injection, - verifies native version output, and returns generated file digests. -- `internal/gitea` verifies hosted source tags, manages matching stable release - pages, and inspects and uploads declared attachments through the Gitea REST API. -- `internal/candidate` captures and validates one clean local candidate, checks - its committed release note and local tag state, runs validation once, and - rechecks mutable repository state. -- `internal/git` resolves one effective push destination, applies it to a - command-scoped remote, reads exact authoritative branch and tag refs, and - creates and pushes exact annotated tag objects. -- `internal/publish` coordinates local and remote guards around one validation - run and reports the publication state reached by that invocation. -- `internal/delivery` verifies a tagged checkout and coordinates note, build - identity, hosted page, asset inspection, and additive upload outcomes. -- `cmd/releasekit/internal/cli` parses implemented commands, loads strict JSON - profiles, adapts configured checks, and writes and validates private local - build receipts used for delivery. +See the [CLI contract](../cli.md), [configuration reference](../config.md), +[candidate check guide](../consumers/check.md), +[build guide](../consumers/build.md), +[delivery guide](../consumers/delivery.md), and +[runtime version guide](../consumers/runtime-version.md) for task-oriented use. +Go declarations and GoDoc remain the owners of exact exported contracts. -The executable controller uses the runtime facade and the command-owned CLI -adapter. The adapter uses the process runner and imports neither public facade. -The publication operation coordinates the candidate and Git packages. The -internal Gitea client is documented in the -[Gitea integration guide](../integrations/gitea.md); tagged-source orchestration -is exposed through the public delivery facade and CLI. +## Module and dependencies + +The module is `gitea.maximumdirect.net/eric/ReleaseKit`, with Go language +version `1.25.0`. `go.mod` has no required third-party modules; packages use the +standard library and first-party ReleaseKit packages. `go list ./...` reports +these implemented packages: + +| Package | Responsibility | +| --- | --- | +| `releasekit` | Public orchestration facade and consumer-owned request/result types. | +| `buildinfo` | Public runtime version accessor. | +| `cmd/releasekit` | Executable entry point, command routing, output, and exit status. | +| `cmd/releasekit/internal/cli` | Command parsing, strict JSON profile loading, configured checks, and private build receipts. | +| `internal/apicheck` | Compiled-export and import-boundary checks run during development. | +| `internal/build` | Selected Go target compilation, version injection, native smoke check, and artifact digests. | +| `internal/candidate` | Stable-version, note, repository-state, candidate capture, and post-validation checks. | +| `internal/delivery` | Tagged-checkout verification and coordination of release pages, assets, and delivery results. | +| `internal/git` | Git command boundary, push-destination resolution, exact ref inspection, and tag operations. | +| `internal/gitea` | Gitea API transport, hosted release pages, asset inspection, manifests, and uploads. | +| `internal/process` | Cancellable child-process execution with per-command environment overlays. | +| `internal/publish` | Publication guards, one validation run, annotated tag creation, push, and recovery state. | +| `internal/runtimeinfo` | Private version lookup used by the runtime facade. | +| `internal/versioncontract` | Shared stable-version rules and linker-symbol identity. | + +The `buildinfo` facade depends only on its small runtime implementation. The +root facade forwards to internal implementation packages. The CLI adapter is +owned under `cmd/releasekit/internal`; implementation packages do not import +either public facade. `internal/apicheck` verifies exported type ownership and +dependency direction with `go run ./internal/apicheck`. These constraints are +also recorded in [ADR 0001](../adr/0001-public-facade.md) and the +[architecture policy](../policy/architecture.md). + +## Capability owners and behavioral evidence + +The following tests are representative evidence from the current offline suite, +not a separate release matrix: + +| Capability | Implementation owner | Existing evidence | +| --- | --- | --- | +| Runtime version lookup and injected application version | `buildinfo`, `internal/runtimeinfo`, `internal/versioncontract`, `internal/build` | `TestVersionInConsumerExecutable`, `TestVersion` | +| Candidate capture, committed note, one validation, and rechecks | `releasekit.Check`, `internal/candidate`, `cmd/releasekit/internal/cli` | `TestCheckCapturesCandidateAndCallsValidationOnce`, `TestCheckRechecksHeadAndWorktreeAfterCallback`, `TestCheckCommandBindsConfiguredChecksToCapturedCandidate` | +| Authoritative endpoint and exact annotated tag publication | `releasekit.Publish`, `internal/publish`, `internal/git` | `TestPublishPushesOnlyTheCapturedAnnotatedTag`, `TestResolveUsesPushURLAndQueriesWithoutMutation` | +| Publication partial and uncertain recovery | `internal/publish` | `TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished`, `TestPublishLostAcknowledgmentConfirmsExactRemoteObject`, `TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError` | +| Cross-builds, version smoke checks, empty target sets, and partial outputs | `releasekit.Build`, `internal/build`, `buildinfo` | `TestBuildCreatesSelectedTargetsAndInjectsVersion`, `TestBuildWithNoTargetsDoesNotInvokeCompiler`, `TestBuildReturnsPartialArtifactsAfterTargetFailure` | +| Page-only and binary tagged-source delivery | `releasekit.Deliver`, `internal/delivery`, `internal/gitea`, CLI | `TestDeliverPageOnlyCreatesAndReusesRelease`, `TestDeliverBuildsTaggedArtifactsAndReusesAssets`, `TestDeliverRejectsTamperedAssetsAndStaleReceiptBeforeRemoteWrites` | +| Page, manifest, asset comparison, and additive retry outcomes | `internal/gitea` | `TestEnsureReleaseCreatesMissingPageFromCommittedNote`, `TestInspectAssetsDetectsSameNameAndSizeWithDifferentBytes`, `TestUploadMissingPartialFailureThenRerunOnlyMissingAssets` | +| CLI profiles and prepared Woodpecker sequences | `cmd/releasekit`, `cmd/releasekit/internal/cli`, `examples/woodpecker/` | `TestLoadSettingsRejectsInvalidProfiles`, `TestWoodpeckerDeliveryCommandSequences`, `TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout` | + +Run the complete suite with `go test ./...`. The public API and import boundary +check is `go run ./internal/apicheck`. Local HTTP and Git fixtures exercise +publication and delivery without real credentials or a hosted service. + +## Integration references + +The [Gitea integration guide](../integrations/gitea.md) owns the HTTP contract +and hosted response handling. The [Woodpecker examples](../../examples/woodpecker/) +are prepared integrations; their YAML is not active in this repository, and no +live Woodpecker runner, configured secret, or hosted delivery has been used. +Consumer migrations and measurement of removed consumer infrastructure remain +future adoption work. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 019326a..2e61168 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # ReleaseKit staged implementation plan -Status: In progress. Stages 1–17 are complete; later stages remain pending. +Status: Complete. Stages 1–18 are complete. Date: 2026-10-05 @@ -170,8 +170,10 @@ directory. A profile supplies product identity, remote, candidate commands, optional build specification, and optional Gitea delivery declaration. The command supplies the version rather than persisting it in the profile. -Use this eventual profile shape; add each optional responsibility only when its -stage implements it: +This composite profile shows the implemented fields together; working +[source-only](../../examples/releasekit.json) and +[binary-producing](../../examples/releasekit-binary.json) profiles are maintained +under `examples/`: ```json { @@ -192,8 +194,7 @@ stage implements it: } ``` -This is a planned example, not an existing file or working invocation. Command -entries also accept an `env` map. Run argument vectors directly, without +Command entries also accept an `env` map. Run argument vectors directly, without implicit shell parsing. A repository that needs shell syntax selects `sh` or `bash` explicitly. Run commands in the captured repository directory and supply `RELEASEKIT_VERSION` and `RELEASEKIT_CANDIDATE` for candidate-specific checks. @@ -920,7 +921,7 @@ was used. ## Stage 18: Complete the initial implementation and handoff documentation -Status: Pending. Depends on Stage 17. +Status: Complete. Depends on Stage 17. 1. Map each initial capability in the feature roadmap to its implemented owner and existing behavioral evidence. Record the concrete package and dependency @@ -946,6 +947,26 @@ 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. +Evidence and handoff: `docs/internal/overview.md` records both public Go +facades, all 14 implemented Go packages, the absence of third-party module +dependencies, capability ownership, and representative behavioral tests. The +README and canonical CLI, configuration, consumer, integration, development, +and release documents describe the implemented behavior; the policy and product +roadmaps no longer present completed facade, delivery, or workflow work as +pending. `go test ./...`, `go run ./internal/apicheck`, local Markdown link and +fragment checks, and prose whitespace checks pass. All three maintained +Woodpecker examples parse with local PyYAML 6.0.3, with the token mapped only in +each delivery step. Local Git and HTTP fixtures exercise source-only delivery, +binary delivery, publication recovery, and the ReleaseKit tagged-source workflow. + +The Woodpecker workflows remain prepared, not activated. No live runner, +configured deployment secret, immutable deployment pin, hosted Gitea delivery, +or ReleaseKit source release was used or verified. Consumer migrations and +measurement of removed consumer infrastructure remain future adoption work. +The implementation is ready for the maintainer's subsequent architecture +review; broader testing and release or deployment decisions remain outside this +completed implementation sequence. + ## Coverage of the feature roadmap | Initial target responsibility | Implementing stages | diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index ecadecc..7ff9c2a 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -1,8 +1,8 @@ # Adopt the policy framework -Status: Policy adoption complete. Source publication and its maintainer runbook -are implemented; no ReleaseKit release has been published. Executable delivery -remains pending. +Status: Policy adoption complete. Source publication, its maintainer runbook, +and prepared hosted note-page delivery are implemented; no ReleaseKit release +has been published. Binary distribution remains deferred. Date: 2026-10-05 @@ -130,8 +130,9 @@ policy has separate defaults for applications and libraries. - [x] Adopt the general versioning, compatibility, integrity, immutability, and successful-tag-push completion rules. -- [x] Select source only as ReleaseKit's initial deliverable in the release - policy. Supporting downstream cross-builds does not declare ReleaseKit binaries. +- [x] Select the immutable source tag as the source-completion point and the + hosted note page as a separate asynchronous deliverable. Supporting downstream + cross-builds does not declare ReleaseKit binaries. - [x] Add `docs/release.md` alongside the first working publication command, documenting real prerequisites, authoritative remote, branch, validation, publication, and failure recovery. @@ -145,8 +146,8 @@ policy has separate defaults for applications and libraries. separate. This task is deferred unless executable deliverables are selected. The publication command, its automated guards, offline candidate validation, -and executable maintainer runbook are implemented. This adoption does not claim -that a ReleaseKit version has been published. +executable maintainer runbook, and prepared hosted-page workflow are implemented. +This adoption does not claim that a ReleaseKit version has been published. ## Validation and completion @@ -157,8 +158,8 @@ examples added later require appropriate execution checks. Adoption is complete when the tailored policy set, contributor navigation, documentation ownership, and licensing notices are coherent and verified. The -release-path stage may remain pending until publication is implemented; record -that status without documenting an unavailable command as usable. +source-publication command and hosted-page delivery are implemented; actual +publication and binary distribution remain outside policy adoption. Do not inherit PromptKit's or ConfigKit's extra release gates automatically. Select additional checks only for identified ReleaseKit risks, recording their @@ -169,13 +170,14 @@ approval, and CI polling are not additional adoption or release gates. The seven policies, root agent orientation, developer reading guide, documentation ownership, project grant, attribution, license texts, source publication command, -and maintainer runbook are in place. The product proposal lives at -`docs/roadmap/releasekit.md`; `ideas.md` remains a navigation pointer. Executable -delivery remains pending, and no ReleaseKit release has been published. +maintainer runbook, and prepared hosted-page delivery are in place. The product +proposal lives at `docs/roadmap/releasekit.md`; `ideas.md` remains a navigation +pointer. Binary distribution is deferred, and no ReleaseKit release has been +published. Verification covers local file and fragment links, per-policy source revision and base version, removed template adoption sections, attribution scope and pinned notice destinations, verbatim license bytes, and prose whitespace. The preserved ADR decision and relocated proposal are checked against their pre-adoption source. -ReleaseKit's source publication command and runbook are implemented; executable -delivery declarations remain pending under stage 4. +ReleaseKit's source publication command, runbook, and hosted-page deliverable are +implemented; binary delivery declarations remain deferred under stage 4. diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index 0e15720..0c66e7e 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -1,14 +1,16 @@ # ReleaseKit: shared release process -This is a proposal based on a review of PromptKit, ConfigKit, Audita, Notarius, -Narratio, and Scriptorium on 2026-09-29. The implementation plan records the -current implemented boundary; the internal Gitea page and asset-delivery -client is implemented, while facade/CLI integration and broader integrations -remain planned. The public facade architecture is -accepted in [ADR 0001](../adr/0001-public-facade.md) and is implemented for -runtime version, candidate validation, and source publication. +This proposal records a review of PromptKit, ConfigKit, Audita, Notarius, +Narratio, and Scriptorium on 2026-09-29. The initial library, CLI, build and +delivery paths, and prepared Woodpecker examples are implemented; the +[implementation plan](implementation.md) records the completed boundary and +evidence. The public facade architecture is accepted in +[ADR 0001](../adr/0001-public-facade.md) and implemented for runtime version, +candidate validation, source publication, selected-target builds, and tagged- +source delivery. The [implementation plan](implementation.md) owns ordered stages, execution -instructions, acceptance checks, and progress toward this target state. +instructions, acceptance checks, and implementation status. Consumer migration +and measurement of local infrastructure reduction remain future adoption work. ## Opportunity @@ -29,7 +31,7 @@ of publication scripts, 150–250 lines of checks and builders, and 400–500 li of repeated publication tests. ReleaseKit would gain its own implementation and tests, so this is a reduction in local code, not a net line-count saving. -## Proposed publication standard +## Selected publication standard 1. Prepare and commit a version-matched note at `docs/releases/.md`. 2. Publish the candidate commit to authoritative `main` before invoking the