From e4be7fa6993747666c2528f58e8c636e52e6f504 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 6 Oct 2026 15:24:19 +0000 Subject: [PATCH] Clarify the audit's developer effort recommendations --- docs/roadmap/audit.md | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index 37001c6..b7fcb29 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -12,6 +12,11 @@ Shared conventions serve these goals by giving routine decisions one owner. Applications supply product facts and product-specific checks; ReleaseKit owns the procedure, sensible defaults, and recovery guidance. +Evaluate recommendations by the application code they remove, the shared logic +they consolidate, and the recurring decisions they eliminate. Standardization, +configuration options, and diagnostic detail are useful when they reduce that +work. Keep routine release decisions inside ReleaseKit. + The core direction is sound. Retain the publication/delivery separation, narrow public facades, standard artifact naming, version injection, and content-aware retries. Fix the reproduced validation and recovery defects in F1–F2 before @@ -160,8 +165,8 @@ microarchitecture requirements in its **Consequence.** A developer's ambient CPU setting can narrow a binary's hardware compatibility. Different build inputs can also produce a digest conflict during a delivery retry. Existing digest comparison correctly preserves published bytes. -This finding supports predictable defaults; its earlier high-priority assessment -placed too much weight on build-environment standardization. +The practical benefit of addressing this finding is predictable hardware +compatibility with fewer settings for application developers to manage. **Recommendation.** Use ordinary baseline CPU settings and shared build flags internally, with the available compatible Go toolchain. Control incidental @@ -212,11 +217,12 @@ alongside its parsing, presentation, and exit-status responsibilities. and deliver sequence behind the orchestration facade. Verify the local tagged source before expensive compilation, then retain the necessary checks before remote effects. Let the CLI adapt JSON, credentials, and output to that operation. -Use the same build declaration for candidate validation and delivery. Decide -whether a concrete consumer needs caller-provided builds, as discussed in -Open Question 3. Keep separate building useful for local development. The ordinary -consumer workflow should complete delivery in one invocation; advanced artifact -handoffs can use private coordination data when needed. +Use the same build declaration for candidate validation and delivery. Support +caller-provided builds for concrete needs such as retrying with retained +artifacts, as discussed in Open Question 3. Keep separate building useful for +local development. The ordinary consumer workflow should complete delivery in +one invocation; advanced artifact handoffs can use private coordination data +when needed. ### F6 — Adoption priority: shared deployment still depends on copied mechanics @@ -338,7 +344,9 @@ reductions in application maintenance or developer effort. product-specific checks. ReleaseKit owns the command and its routine environment settings. Migrate repeated suite invocations out of application scripts. Add alternative invocation settings when an actual consumer requirement establishes -their value. This gives developers one ordinary validation path to understand. +their value. An application adding an example check should declare that check +and receive the standard suite automatically. This gives developers one ordinary +validation path to understand. **Viable alternative:** Keep a replacement callback or complete validation command for products with unusual test layouts. This is a simple composition @@ -353,7 +361,8 @@ settings, and shared build flags. Handle incidental environment settings interna so developers can rely on the selected target's expected compatibility. Keep application configuration small. Toolchain-dependent byte differences are acceptable; digest checks preserve existing published content, and retained -artifacts support retries requiring the same bytes. +artifacts support retries requiring the same bytes. ReleaseKit can own baseline +settings internally while applications declare their packages and targets. **Viable alternative:** A shared CI image can supply a centrally selected Go version and build environment when this makes installation and support easier. @@ -368,7 +377,9 @@ Explicit hardware variants can be added for a demonstrated product need. selected-target builds, temporary storage, checksums, uploads, and cleanup. Use it from the CLI so both interfaces share the procedure. Retain separate building for local development and support prebuilt delivery where a concrete -handoff requirement justifies it. This minimizes consumer orchestration code. +handoff or retry requirement justifies it. Routine delivery should require one +invocation, with ReleaseKit managing the artifact lifecycle. This minimizes +consumer orchestration code. **Viable alternative:** Keep separate build and delivery primitives with a maintained composition helper. This suits consumers that require credential @@ -381,8 +392,9 @@ operational separation they need. **Recommended:** Choose the simplest maintained entry point for installation, updates, and delivery. Begin with versioned source installation if it keeps consumer integration small. Centralize reusable setup and provide one clear -upgrade procedure. Assess packaging by the consumer code and recurring developer -work it removes. +upgrade procedure. Applications should select a ReleaseKit version and supply +product settings and credentials; shared integration should own routine setup. +Assess packaging by the consumer code and recurring developer work it removes. **Viable alternative:** Publish a maintained CI image containing ReleaseKit and a compatible Go/Git environment when it substantially reduces setup. The image @@ -396,7 +408,9 @@ applications a small configuration and a routine invocation. **Recommended:** Use exclusive outcome categories: matching, uploaded, known pending, conflicting, and uncertain. Present ordinary callers with completion or a clear failure and recovery instruction. Keep asset details available for -diagnostics. Consistent categories simplify implementation and interpretation. +diagnostics. Derive recovery guidance centrally so each application can present +the result directly. Consistent categories simplify implementation and +interpretation. **Viable alternative:** Pending includes every unfinished declaration, with conflicting/uncertain as diagnostic subsets. This can simplify a progress UI