Goal
make the release preparation sequence executable end to end.
Background and evidence
Release-preparation review of a90aa1429647b6eb4820a01aabe37799ca55ad5e on macOS arm64. Bash 5.3.20; ordinary local POSIX filesystem.
docs/release-process.md step 3 tells a maintainer to update VERSION, README, and CHANGELOG, but omits the checked-in lib/bash/base-bash-libs.release version. Following those steps for 2.2.0 in an isolated copy fails the documented validator with:
Repository baseline is present.
Documentation contract passed.
Embedded release metadata version (2.1.0) does not match VERSION (2.2.0).
The guide also asks for artifacts built from <full-tag-sha> at step 4, before the release-prep PR is merged at step 6 and before the tag preflight/publication at steps 7-8. A maintainer needs a clear distinction between candidate rehearsal artifacts and final artifacts bound to the eventual merged release commit; the current order cannot literally be followed with a final tag SHA.
write_release_metadata updates metadata inside a built artifact, but does not fix the source checkout required by tests/validate.sh.
Scope and acceptance criteria
- List every source metadata file required when advancing VERSION, including the embedded release identity version.
- Preserve the intended checkout provenance placeholders rather than committing a self-referential hash.
- Separate pre-merge rehearsal from the final clean merged commit, tag absence check, publish, and remote verification.
- Explain the final full commit SHA used to build/bind artifacts before the tag exists and avoid an instruction that requires precreating a forbidden tag.
- Add a release-prep documentation/fixture check so the prescribed metadata transition passes the baseline.
Validation
Rehearse the documented metadata update in a disposable checkout; run validation through the release metadata checks and exercise existing release guard fixtures. Do not publish.
Source references:
Non-goals
No release publication or unrelated API redesign. Preserve documented compatibility except for the defective behavior identified above.
Project fields
- Project:
base-bash-libs
- Status:
Ready
- Priority:
P2
- Area:
Docs
- Initiative:
Adoption Polish
- Size:
S
- Milestone:
v2.2.0
Agent assignment
Assignee: @codeforester. Implementation may be handled through the normal issue-backed worktree and reviewed PR workflow.
Goal
make the release preparation sequence executable end to end.
Background and evidence
Release-preparation review of
a90aa1429647b6eb4820a01aabe37799ca55ad5eon macOS arm64. Bash 5.3.20; ordinary local POSIX filesystem.docs/release-process.mdstep 3 tells a maintainer to update VERSION, README, and CHANGELOG, but omits the checked-inlib/bash/base-bash-libs.releaseversion. Following those steps for 2.2.0 in an isolated copy fails the documented validator with:The guide also asks for artifacts built from
<full-tag-sha>at step 4, before the release-prep PR is merged at step 6 and before the tag preflight/publication at steps 7-8. A maintainer needs a clear distinction between candidate rehearsal artifacts and final artifacts bound to the eventual merged release commit; the current order cannot literally be followed with a final tag SHA.write_release_metadataupdates metadata inside a built artifact, but does not fix the source checkout required bytests/validate.sh.Scope and acceptance criteria
Validation
Rehearse the documented metadata update in a disposable checkout; run validation through the release metadata checks and exercise existing release guard fixtures. Do not publish.
Source references:
Non-goals
No release publication or unrelated API redesign. Preserve documented compatibility except for the defective behavior identified above.
Project fields
base-bash-libsReadyP2DocsAdoption PolishSv2.2.0Agent assignment
Assignee: @codeforester. Implementation may be handled through the normal issue-backed worktree and reviewed PR workflow.