From 547be2d9ab9f2f2c2c8d7c49f3bc3024cb724d28 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 9 Nov 2026 15:02:35 +0000 Subject: [PATCH] Resolve ReleaseKit workflow and validator selection --- docs/roadmap/commandkit.md | 3 +- docs/roadmap/library-adoption.md | 150 +++++++++++++++++++------------ 2 files changed, 95 insertions(+), 58 deletions(-) diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 12f4b58..a318454 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -304,7 +304,8 @@ integration acceptance. No additional upstream request was identified. ### Output-Failure Behavior -This is decision 2 in the [master discussion order](library-adoption.md#open-decisions). +This is the remaining open decision in the +[master roadmap](library-adoption.md#open-decisions). Specify how failed transcript, report, debug-artifact, and standard reporter writes influence the process outcome. The existing visibility rules and prohibition on a successful completion summary after required-output failure remain selected. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index cbefaf9..17d210e 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -4,7 +4,8 @@ **Status:** Agreed direction with proposed sequencing. Initial outlines only; no implementation or dependency changes have been made for this plan. Resolve -the two remaining [open decisions](#open-decisions) in the listed order. +the remaining [output-failure decision](#open-decisions) before implementation +planning. ReleaseKit workflow and validator selection are resolved below. ## Objective and Document Ownership @@ -101,6 +102,7 @@ satisfied as recorded below: | `go.maximumdirect.net/commandkit` | v0.6.0 | `1613ff95cab60581de5d86f6e9e2a3cc091a44a0` | | `go.maximumdirect.net/ckconfig` | v0.6.0 | `5ed947bd26bf2c6d70d1d748b693eca89f18d605` | | `go.maximumdirect.net/ckprompt` | v0.6.0 | `1ca660e35fb58fc0dc318e411afb6e3631a40ef1` | +| `go.maximumdirect.net/releasekit` | v0.9.0 | `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4` | The integration tags are `integrations/ckconfig/v0.6.0` and `integrations/ckprompt/v0.6.0` in CommandKit's repository. Use the @@ -117,11 +119,11 @@ records the API contract and review evidence. The selected release set removes the upstream availability blocker; Audita implementation and acceptance remain pending under the sequence below. -ReleaseKit v0.9.0 at `go.maximumdirect.net/releasekit` is also a required target. -The library graph already brings in that version, but Audita's direct tool still -uses old-path v0.4.1. Direct adoption includes reviewing the v0.9.0 release and -validator APIs; the earlier integration checks do not establish its suitability -for Audita's complete release workflow. +The reviewed target dependency graph includes ReleaseKit v0.9.0, but Audita's +direct tool still uses old-path v0.4.1. The release, workflow, and validator review +is complete, with no identified upstream blocker. The agreed +[ReleaseKit adoption work](#releasekit-adoption-work) below remains to be +implemented and accepted in Audita. ## Proposed Order of Operations @@ -181,30 +183,82 @@ implementation stage is ready. ## ReleaseKit Adoption Work -The concrete workflow and validator selection remain -[open decision 1](#1-releasekit-workflow-and-validator-selection). +### Workflow and Validator Selection — Resolved -1. Review v0.9.0's supported release workflow, validators, and version integration. - Inventory Audita's launcher, scripts, CI responsibilities, and local release - checks against those facilities. Select the best target workflow without - preserving old invocation or validation behavior for compatibility. -2. Move the direct tool and version integration to the new module identity. - Replace local orchestration and validation with supported ReleaseKit facilities - wherever possible. Keep repository-specific configuration and necessary domain - integration; remove redundant wrappers and checks. -3. Select ReleaseKit-owned validators freely according to the desired workflow; - there is no numerical limit or presumption against adopting upstream checks. - For every retained local release validator, record its domain-specific purpose - and why upstream facilities do not satisfy it. Remove checks without that - justification, and propose reusable missing capabilities upstream. -4. Reconcile the release policy and runbook with the selected workflow as it lands, - including provisions that would otherwise restrict the chosen upstream - validators. Update CI, version reporting, and attribution as needed. The - current runbook is a baseline to replace, not a compatibility constraint. -5. Verify the selected validators, version identity, and release orchestration - through non-publishing checks. Cover any justified domain validation and verify - that removed local checks are no longer duplicated around upstream validation. - Adoption work does not authorize publishing a release. +Adopt ReleaseKit v0.9.0's standard publication and asynchronous delivery workflow. +This implements the ownership decision in [ADR 0001](../adr/0001-releasekit.md). +Audita already delegates publication, builds, and delivery to ReleaseKit; the +upgrade modernizes that integration and removes duplicated generic tests. No +additional Audita-owned release validator or upstream feature request is needed +for the reviewed requirements. Audita's domain tests remain in the ordinary +offline suite executed by ReleaseKit. + +The selected workflow is: + +1. Prepare the release note and final committed candidate, then push that + candidate to the authoritative `main` branch. +2. Use one ReleaseKit `publish` invocation to validate the candidate, check the + required builds and version identity, and publish the annotated tag. Keep + `check` available for diagnosis; do not require it before `publish` repeats + validation. +3. Use the maintained Woodpecker tag-delivery workflow to invoke `ci-deliver` + from the tagged source. Deliver the hosted release page, Linux amd64 and arm64 + binaries, and checksums asynchronously. Successful tag publication completes + the source release; report artifact delivery separately. +4. Use ReleaseKit's standard recovery commands and procedures for publication + and delivery failures, without a separate Audita recovery layer. + +Use the reviewed upstream [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/publish.md), +[delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/delivery.md), +and [configuration reference](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/config.md) +for standard behavior. Select these checks through the native release profile: + +| Capability | Selection | Reason | +| --- | --- | --- | +| Standard offline Go test suite and candidate/publication guards | Retain ReleaseKit's built-in checks | Validate Audita's behavior and the exact source being published. | +| Race detection | `validation.go.race: true` | Audita's concurrent processing and cancellation warrant race detection in the single standard suite. | +| Full Go vet | `validation.go.full_vet: true` | Add static checks; ReleaseKit disables test-time vet to avoid duplication. | +| Go formatting | `validation.go_format: true` | Enforce consistent formatting through the shared implementation. | +| Local Markdown links and heading references | `validation.markdown: {}` | Protect documentation navigation using upstream defaults. | +| Committed workspace files | `validation.module_distribution.workspace_files: true` | Keep development workspace files out of releases. | +| Filesystem module replacements | `validation.module_distribution.local_replacements: true` | Prevent releases depending on local dependency checkouts. | +| Application builds and version identity | Retain `build.targets` for `linux/amd64` and `linux/arm64`, with ReleaseKit's native version check | Verify the required production binaries and their embedded version. | +| Additional compile-only targets | Omit `validation.go.compile_targets` initially | Limited additional value alongside the required application builds. | +| File-size limits | Omit `validation.file_size` initially | No application-specific size ceiling has been selected. | +| Forbidden-file paths | Omit `validation.forbidden_files` initially | Delivery uses the existing CI secret; no release-token file is configured. | + +Do not duplicate these checks in profile `checks`, custom release hooks, or +surrounding scripts. Any future local release validator requires a documented +domain-specific justification; reusable gaps should be addressed upstream. + +### Required Implementation and Acceptance + +1. Migrate the direct tool declaration and runtime `buildinfo` import together + to `go.maximumdirect.net/releasekit` v0.9.0 so build-time version injection + and runtime reporting use the same implementation. Remove superseded direct + dependencies and tool registrations. +2. Update the launcher and Woodpecker workflow from the v0.9.0 + [adoption recipes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/consumers/adoption.md) + and [tag-delivery template](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/examples/woodpecker/tag-delivery.yml). + Include Go host-platform selection and invocation by the full tool-package + path; a dependency upgrade alone does not update copied recipes. Keep only + necessary repository wiring around the maintained upstream workflow. +3. Apply the selected checks in `releasekit.json`, add the required + `delivery.forge: "gitea"`, and retain Audita's product, production targets, + delivery destination, and CI secret mapping. Align local validation and CI + with the selected Go 1.27-or-newer toolchain. Include the C compiler and cgo + prerequisites required by race detection in the maintainer setup. +4. Remove generic launcher and bootstrap tests already covered by ReleaseKit. + Retain focused checks for Audita's product settings, targets, destination, + and version integration. Reconcile the release policy and runbook with the + selected workflow and validator rationale as implementation lands; update + attribution and link to standard upstream recovery documentation. +5. Verify the selected validators, both production builds, version identity, + and assembled launcher/CI wiring without publishing a release. Confirm that + removed local checks are no longer duplicated around upstream validation. + Hosted-delivery integration remains implementation acceptance work; the + disposable local check below does not establish it. Adoption work does not + authorize publishing a release. ## Shared Evidence, Validation, and Completion @@ -222,6 +276,11 @@ contracts. Disposable checks using Go 1.27.3 established: covering debug capture, reporting-mode ordering, aliases, and quiet transcript destination validation. The assembled graph retains the selected ConfigKit and PromptKit versions and brings in ReleaseKit v0.9.0. +- A disposable Audita copy with the ReleaseKit tool and runtime version import + migrated to v0.9.0, and toolchain references aligned, passes the selected native + validators, Linux amd64 and arm64 builds, and the native version-output check. + This exercised local `check` only; no release was published and hosted delivery + was not exercised. These are review results, not implementation acceptance. They involved no live provider calls and do not prove migrated Audita behavior or cross-platform @@ -250,35 +309,12 @@ and retain shared license texts. Do not copy upstream policy inventories. ## Open Decisions -Work through these decisions in order. Recommendations below remain proposals; -the existing adoption principles remain in force. CommandKit release selection -is resolved in the dependency set above. +CommandKit release selection and ReleaseKit workflow/validator selection are +resolved above. One decision remains before implementation planning. -### 1. ReleaseKit Workflow and Validator Selection - -Inventory the current launcher, scripts, CI responsibilities, version integration, -and local release checks against ReleaseKit v0.9.0. Select the concrete workflow, -upstream validators, machinery to remove, and any remaining domain-specific -checks. ReleaseKit adoption and its target version are already agreed. - -**Recommendation:** use the upstream-supported release workflow to own as much -orchestration and validation as it supports. Select all ReleaseKit-owned validators -appropriate to Audita's release requirements, and retain local validation only -with a documented domain-specific justification. This directly reduces Audita's -maintenance burden and follows the suite's standard path. The inventory must -establish which facilities cover the current responsibilities and whether an -upstream request is needed. - -**Alternative:** let CI explicitly sequence ReleaseKit commands through a thin -repository-owned orchestration layer where the upstream workflow cannot express -Audita's required scheduling or platform coordination. Validation still belongs -upstream except for justified domain checks. This can fit concrete CI needs but -retains local sequencing to maintain; prefer an upstream enhancement for a -reusable gap rather than permanently duplicating release machinery. - -### 2. Output-Failure Behavior +### Output-Failure Behavior Resolve the [output-failure decision](commandkit.md#output-failure-behavior) in -the CommandKit roadmap after the ReleaseKit selection above. That document owns the -recommendation, alternative, and behavior contract. This decision completes the +the CommandKit roadmap. That document owns the recommendation, alternative, and +behavior contract. This decision completes the remaining write-failure detail before implementing the output/reporting boundary.