eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Clarify the audit's developer effort recommendations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 15:24:19 +00:00
parent 85b2b39fb6
commit e4be7fa699
1 changed files with 27 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/roadmap/audit.md
View File

@@ -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 Applications supply product facts and product-specific checks; ReleaseKit owns
the procedure, sensible defaults, and recovery guidance. 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 The core direction is sound. Retain the publication/delivery separation, narrow
public facades, standard artifact naming, version injection, and content-aware public facades, standard artifact naming, version injection, and content-aware
retries. Fix the reproduced validation and recovery defects in F1–F2 before 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 **Consequence.** A developer's ambient CPU setting can narrow a binary's hardware
compatibility. Different build inputs can also produce a digest conflict during compatibility. Different build inputs can also produce a digest conflict during
a delivery retry. Existing digest comparison correctly preserves published bytes. a delivery retry. Existing digest comparison correctly preserves published bytes.
This finding supports predictable defaults; its earlier high-priority assessment The practical benefit of addressing this finding is predictable hardware
placed too much weight on build-environment standardization. compatibility with fewer settings for application developers to manage.
**Recommendation.** Use ordinary baseline CPU settings and shared build flags **Recommendation.** Use ordinary baseline CPU settings and shared build flags
internally, with the available compatible Go toolchain. Control incidental 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 and deliver sequence behind the orchestration facade. Verify the local tagged
source before expensive compilation, then retain the necessary checks before source before expensive compilation, then retain the necessary checks before
remote effects. Let the CLI adapt JSON, credentials, and output to that operation. remote effects. Let the CLI adapt JSON, credentials, and output to that operation.
Use the same build declaration for candidate validation and delivery. Decide Use the same build declaration for candidate validation and delivery. Support
whether a concrete consumer needs caller-provided builds, as discussed in caller-provided builds for concrete needs such as retrying with retained
Open Question 3. Keep separate building useful for local development. The ordinary artifacts, as discussed in Open Question 3. Keep separate building useful for
consumer workflow should complete delivery in one invocation; advanced artifact local development. The ordinary consumer workflow should complete delivery in
handoffs can use private coordination data when needed. one invocation; advanced artifact handoffs can use private coordination data
when needed.
### F6 — Adoption priority: shared deployment still depends on copied mechanics ### 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 product-specific checks. ReleaseKit owns the command and its routine environment
settings. Migrate repeated suite invocations out of application scripts. Add settings. Migrate repeated suite invocations out of application scripts. Add
alternative invocation settings when an actual consumer requirement establishes 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 **Viable alternative:** Keep a replacement callback or complete validation
command for products with unusual test layouts. This is a simple composition 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 so developers can rely on the selected target's expected compatibility. Keep
application configuration small. Toolchain-dependent byte differences are application configuration small. Toolchain-dependent byte differences are
acceptable; digest checks preserve existing published content, and retained 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 **Viable alternative:** A shared CI image can supply a centrally selected Go
version and build environment when this makes installation and support easier. 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. selected-target builds, temporary storage, checksums, uploads, and cleanup.
Use it from the CLI so both interfaces share the procedure. Retain separate Use it from the CLI so both interfaces share the procedure. Retain separate
building for local development and support prebuilt delivery where a concrete 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 **Viable alternative:** Keep separate build and delivery primitives with a
maintained composition helper. This suits consumers that require credential 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, **Recommended:** Choose the simplest maintained entry point for installation,
updates, and delivery. Begin with versioned source installation if it keeps updates, and delivery. Begin with versioned source installation if it keeps
consumer integration small. Centralize reusable setup and provide one clear consumer integration small. Centralize reusable setup and provide one clear
upgrade procedure. Assess packaging by the consumer code and recurring developer upgrade procedure. Applications should select a ReleaseKit version and supply
work it removes. 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 **Viable alternative:** Publish a maintained CI image containing ReleaseKit and
a compatible Go/Git environment when it substantially reduces setup. The image 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 **Recommended:** Use exclusive outcome categories: matching, uploaded, known
pending, conflicting, and uncertain. Present ordinary callers with completion or pending, conflicting, and uncertain. Present ordinary callers with completion or
a clear failure and recovery instruction. Keep asset details available for 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 **Viable alternative:** Pending includes every unfinished declaration, with
conflicting/uncertain as diagnostic subsets. This can simplify a progress UI conflicting/uncertain as diagnostic subsets. This can simplify a progress UI