From 0a3e4d2892865a75e295d36ac5da3163f7e2980f Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Thu, 8 Oct 2026 06:52:16 +0530 Subject: [PATCH] docs: align current release documentation --- CHANGELOG.md | 6 +++++- README.md | 16 +++++++++------- docs/consumer-validation-status.md | 20 ++++++++++++-------- docs/discovery/awesome-bash.md | 2 +- docs/pinned-consumption.md | 4 ++-- docs/v2/quickstart.md | 13 +++++++------ docs/versioning-policy.md | 20 ++++++++++---------- tests/docs-contract.sh | 21 +++++++++++---------- 8 files changed, 57 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc9627e..75c9341 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,11 @@ and versions are tracked in the repo-root `VERSION` file. ## [Unreleased] -No unreleased changes yet. +### Documentation + +- Aligned the current-release onboarding, pinned-consumption, versioning, and + validation references with the published v2.2.0 release and its immutable + source commit. ## [2.2.0] - 2026-10-07 diff --git a/README.md b/README.md index 32e303f..739dbfc 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,9 @@ platform, license, and release policy](https://github.com/basefoundry/base/blob/ `BASE_BASH_LIBS_VERSION` constant. - [`lib/bash/process/lib_process.sh`](lib/bash/process/README.md) Preview-only process-supervision primitives for owner-guardian liveness and - asynchronous cleanup, layered on the stdlib. This post-GA module is included - in the immutable `v2.1.0` release but is not part of the stable API. + asynchronous cleanup, layered on the stdlib. This post-GA module first + shipped in `v2.1.0` and is included in the current immutable `v2.2.0` + release, but is not part of the stable API. - [`lib/bash/file/lib_file.sh`](lib/bash/file/README.md) File editing helpers built on the stdlib, including idempotent marker-delimited file section updates. @@ -160,9 +161,9 @@ moving default branch: mkdir -p vendor git clone https://github.com/basefoundry/base-bash-libs.git vendor/base-bash-libs git -C vendor/base-bash-libs checkout --detach \ - 36fec50c446dcea8c521a1ba3e7fee2394f169c0 + d8894bf4453e6b6beaa6de7ce2e082497cb236f2 test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = \ - 36fec50c446dcea8c521a1ba3e7fee2394f169c0 + d8894bf4453e6b6beaa6de7ce2e082497cb236f2 ``` Source the stdlib from that checkout: @@ -237,13 +238,14 @@ The repo-root `VERSION` file is the source of truth for the package version. The top strip in this README and the runtime `BASE_BASH_LIBS_VERSION` constant are validated against that file. -`v2.1.0` is the current stable release. It is a post-GA release on the v2 line; +`v2.2.0` is the current stable release. It is a post-GA release on the v2 line; SemVer compatibility guarantees began at v2.0.0. See the [versioning and release-line policy](docs/versioning-policy.md) for immutable consumption and the post-GA support contract. -The `process` module remains preview-only. It is included in `v2.1.0`, but is -not part of the stable API; consumers pinned to `v2.0.0` do not have it. +The `process` module remains preview-only. It first shipped in `v2.1.0` and is +included in `v2.2.0`, but is not part of the stable API; consumers pinned to +`v2.0.0` do not have it. Pinned checkout, archive, Homebrew, vendored, and standalone consumption is documented in [`docs/pinned-consumption.md`](docs/pinned-consumption.md). diff --git a/docs/consumer-validation-status.md b/docs/consumer-validation-status.md index deb0e48..7822024 100644 --- a/docs/consumer-validation-status.md +++ b/docs/consumer-validation-status.md @@ -1,6 +1,6 @@ # Consumer validation status -Ledger reconciled: 2026-10-07 +Ledger reconciled: 2026-10-08 The v2.0.0 rows below are historical GA evidence. The current canary snapshot is recorded separately and must not be read as a new first-party release or @@ -23,12 +23,16 @@ verified. The canonical archive SHA256 is ## Current canary snapshot -On 2026-10-05, the scheduled [Framework Compatibility run -#37327900680](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37327900680) -passed all four candidate jobs: the immutable v2.0.0 baseline and current -supported v2.1.0 release on Ubuntu 24.04 and macOS 14. This validates the demo's -black-box compatibility path; it does not change the committed v2.0.0 vendor -pin or promote the historical GA rows below. +The published current release is `base-bash-libs` v2.2.0. The [v2.2.0 +release validation run](https://github.com/basefoundry/base-bash-libs/actions/runs/37647096223) +passed the release gates, supported Bash compatibility jobs, macOS 14 and +Ubuntu 24.04 validation, and the downstream Beacon smoke. The corresponding +[Base Bash Demo v0.1.0 release run](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37652182510) +passed its macOS Homebrew Bash, Ubuntu, minimum-Bash, and standalone-artifact +jobs against the immutable v2.2.0 vendor. The earlier [Framework Compatibility +run #37327900680](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37327900680) +remains useful v2.1.0 evidence but predates v2.2.0; none of these first-party +results count as independent adoption evidence. ## Consumer matrix @@ -36,7 +40,7 @@ pin or promote the historical GA rows below. | --- | --- | --- | --- | --- | --- | | Base | First-party direct consumer | published [v1.8.0](https://github.com/basefoundry/base/releases/tag/v1.8.0), commit `26b9af5` | CI and source-checkout workflows pin GA commit `b424376` (v2.0.0) | PR [#1936](https://github.com/basefoundry/base/pull/1936) passed Python/pylint, integration, security, BATS, Ubuntu source-checkout, macOS smoke, and branch policy; v1.8.0 release preflight and publication passed | GA pin and release pass | | Base Demo | First-party representative consumer | merged [#217](https://github.com/basefoundry/base-demo/pull/217) at `fb7a2b6` | CI and source-checkout workflows pin GA commit `b424376` (v2.0.0) | Local full validation and hosted validate, Ubuntu, and source-checkout checks passed | GA pin and validation pass | -| Base Bash Demo | First-party isolated reference consumer | flagship [#6](https://github.com/basefoundry/base-bash-libs-demo/pull/6) at `ff99159`; canary [#7](https://github.com/basefoundry/base-bash-libs-demo/pull/7) at `90c0efb` | Commits the verified canonical v2.0.0 bundle, lock, checksum manifest, provenance, and SPDX SBOM; candidate checks use an explicit release tag or full commit without changing the default pin | Ubuntu, exact Bash 4.2.53, macOS Homebrew Bash, stable-tag [run 33659256428](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/33659256428), and full-commit [run 33659260664](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/33659260664) passed | GA vendor pin and external downstream canary pass; excluded from independent count | +| Base Bash Demo | First-party isolated reference consumer | released [v0.1.0](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.0) at `7acf3c6`; docs and vendor now target v2.2.0 | Commits the verified canonical v2.2.0 bundle, lock, checksum manifest, provenance, and SPDX SBOM; candidate checks use an explicit release tag or full commit without changing the default pin | Ubuntu, exact Bash 4.2.53, macOS Homebrew Bash, and standalone artifact jobs passed in [run 37652182510](https://github.com/basefoundry/base-bash-libs-demo/actions/runs/37652182510) | v2.2.0 first-party release validation pass; excluded from independent count | | BankBuddy | Adjacent repository; no direct `base-bash-libs` reference | `e32561c` | None | Repository validation: **312 passed** | Excluded from the consumer count | | BanyanLabs | Adjacent repository; no direct `base-bash-libs` reference | `15ef6cd` | None | Repository baseline present | Excluded from the consumer count | | Homebrew | First-party package-manager consumer | merged [#85](https://github.com/basefoundry/homebrew-base/pull/85), bottle release `base-v1.8.0` | `base-bash-libs` v2.0.0 bundle and Base v1.8.0 archive are hash-pinned; both macOS bottles published | Both bottle builds and v2 API smoke tests passed; installed GA upgrade, formula tests, and rollback to Base 1.7.0/base-bash-libs 1.4.0 passed | GA formula, bottles, upgrade, and rollback pass | diff --git a/docs/discovery/awesome-bash.md b/docs/discovery/awesome-bash.md index ad3a07a..9871bef 100644 --- a/docs/discovery/awesome-bash.md +++ b/docs/discovery/awesome-bash.md @@ -7,7 +7,7 @@ deliberately not a claim that the project has been accepted upstream. Submit only after a published v2 release has a canonical immutable asset and the following links are public and stable. This record was last reviewed on -2026-10-07 against v2.1.0: +2026-10-08 against v2.2.0: 1. the five-minute adoption path in [`docs/v2/quickstart.md`](../v2/quickstart.md); 2. the support and security policies in [`docs/support-policy.md`](../support-policy.md); diff --git a/docs/pinned-consumption.md b/docs/pinned-consumption.md index 1171da6..73799d3 100644 --- a/docs/pinned-consumption.md +++ b/docs/pinned-consumption.md @@ -27,8 +27,8 @@ Verify the release asset checksum before unpacking it. Keep the complete release commit (when published), and artifact provenance. Then source the stdlib and use only package-relative imports: -The v2.1.0 release's canonical files are the archive, -`base-bash-libs-v2.1.0.SHA256SUMS`, SPDX SBOM, and provenance statement. Do not +The v2.2.0 release's canonical files are the archive, +`base-bash-libs-v2.2.0.SHA256SUMS`, SPDX SBOM, and provenance statement. Do not substitute GitHub's automatic tag archive or a moving branch. Maintainers can re-run the repository-owned `scripts/release-artifact verify-remote` check to confirm that all four files still bind to the annotated tag commit. diff --git a/docs/v2/quickstart.md b/docs/v2/quickstart.md index d15053d..5580ca6 100644 --- a/docs/v2/quickstart.md +++ b/docs/v2/quickstart.md @@ -6,12 +6,12 @@ checks, tests, and a deterministic bundle. ## 1. Select a verified release -Use the published `v2.1.0` tag and its verified commit. The reference is +Use the published `v2.2.0` tag and its verified commit. The reference is intentionally required rather than defaulting to a moving branch: ```bash -export BASE_BASH_LIBS_REF='v2.1.0' -export EXPECTED_BASE_BASH_LIBS_COMMIT='36fec50c446dcea8c521a1ba3e7fee2394f169c0' +export BASE_BASH_LIBS_REF='v2.2.0' +export EXPECTED_BASE_BASH_LIBS_COMMIT='d8894bf4453e6b6beaa6de7ce2e082497cb236f2' mkdir -p vendor git clone https://github.com/basefoundry/base-bash-libs.git vendor/base-bash-libs git -C vendor/base-bash-libs fetch --tags origin "$BASE_BASH_LIBS_REF" @@ -23,9 +23,10 @@ Do not replace the ref with `main`, a short SHA, or an automatically generated archive URL. Verify the published checksum asset before distributing a consumer application. -The preview `process` module is present in this v2.1.0 checkout, but it is not -part of the stable API. Use it only when a consumer explicitly opts into the -preview contract; the stable `gh` API may use it privately. +The preview `process` module is present in this v2.2.0 checkout. It first +shipped in v2.1.0, remains outside the stable API, and should be used only +when a consumer explicitly opts into the preview contract; the stable `gh` API +may use it privately. ## 2. Generate and run an application diff --git a/docs/versioning-policy.md b/docs/versioning-policy.md index 116f056..638bcec 100644 --- a/docs/versioning-policy.md +++ b/docs/versioning-policy.md @@ -2,7 +2,7 @@ ## Current Release Line -`v2.1.0` is the current stable Base Bash release, backed by its verified +`v2.2.0` is the current stable Base Bash release, backed by its verified canonical release asset. `v1.4.0` and earlier releases are historical references; the 5/5 initiative has one stable target and will not create a stable `v1.5.0` or reset the version to 0.x. @@ -11,7 +11,7 @@ Those choices would either hide breaking changes inside the current 1.x compatibility range or move version precedence backward. Post-GA releases use one repository-owned v2 SemVer policy. Compatibility -guarantees began at `v2.0.0`; `v2.1.0` is the current release on that line: +guarantees began at `v2.0.0`; `v2.2.0` is the current release on that line: ```text 2.MINOR.PATCH @@ -60,9 +60,9 @@ sentinel-file override. Maintainers can inspect any candidate without changing GitHub state: ```bash -scripts/release check --version 2.1.0 --manifest base_manifest.yaml -scripts/release plan --version 2.1.0 --manifest base_manifest.yaml -scripts/release publish --version 2.1.0 --manifest base_manifest.yaml --dry-run +scripts/release check --version 2.2.0 --manifest base_manifest.yaml +scripts/release plan --version 2.2.0 --manifest base_manifest.yaml +scripts/release publish --version 2.2.0 --manifest base_manifest.yaml --dry-run ``` The generic `basectl release` command is not a substitute for this guard. Its @@ -72,7 +72,7 @@ artifact, provenance, or GA gates. Before any real publication attempt, run the repository-owned tag preflight: ```bash -scripts/release refs --version 2.1.0 +scripts/release refs --version 2.2.0 ``` The preflight checks both the exact candidate tag in the local checkout and the @@ -126,15 +126,15 @@ The complete checkout, archive, Homebrew, vendored, and standalone verification procedure is maintained in [`pinned-consumption.md`](pinned-consumption.md). Do not install from an unpinned default-branch checkout. Use the canonical -`v2.1.0` release asset and verify its checksum, or pin the stable source to the -full commit resolved from the annotated `v2.1.0` tag: +`v2.2.0` release asset and verify its checksum, or pin the stable source to the +full commit resolved from the annotated `v2.2.0` tag: ```bash git clone https://github.com/basefoundry/base-bash-libs.git vendor/base-bash-libs git -C vendor/base-bash-libs checkout --detach \ - 36fec50c446dcea8c521a1ba3e7fee2394f169c0 + d8894bf4453e6b6beaa6de7ce2e082497cb236f2 test "$(git -C vendor/base-bash-libs rev-parse HEAD)" = \ - 36fec50c446dcea8c521a1ba3e7fee2394f169c0 + d8894bf4453e6b6beaa6de7ce2e082497cb236f2 ``` Prerelease validation must likewise use an immutable prerelease tag resolved to diff --git a/tests/docs-contract.sh b/tests/docs-contract.sh index 921bb19..11a22a0 100755 --- a/tests/docs-contract.sh +++ b/tests/docs-contract.sh @@ -24,34 +24,35 @@ if grep -R -n -E 'checkout[[:space:]]+main|/archive/refs/heads/main|git clone .* exit 1 fi -grep -F "export BASE_BASH_LIBS_REF='v2.1.0'" docs/v2/quickstart.md > /dev/null || { +current_release="v$(< VERSION)" +grep -F "export BASE_BASH_LIBS_REF='$current_release'" docs/v2/quickstart.md > /dev/null || { printf 'The v2 quickstart must use the current published release reference.\n' >&2 exit 1 } -current_release_commit='36fec50c446dcea8c521a1ba3e7fee2394f169c0' -grep -F "$current_release_commit" docs/v2/quickstart.md README.md > /dev/null || { - printf 'The v2 quickstart and source-checkout example must pin the current release commit.\n' >&2 +quickstart_release_commit="$(sed -n "s/^export EXPECTED_BASE_BASH_LIBS_COMMIT='\([0-9a-f]\{40\}\)'$/\1/p" docs/v2/quickstart.md | sed -n '1p')" +[[ -n "$quickstart_release_commit" ]] || { + printf 'The v2 quickstart must pin a full current release commit.\n' >&2 exit 1 } readme_current_release="$(sed -n 's/^`\(v[0-9][^`]*\)` is the current stable release.*$/\1/p' README.md | sed -n '1p')" -[[ "$readme_current_release" == v2.1.0 ]] || { +[[ "$readme_current_release" == "$current_release" ]] || { printf 'README must declare exactly one current stable release.\n' >&2 exit 1 } readme_pin="$(sed -n '/^Pin the checkout to the full current release commit/,/^```$/p' README.md | sed -n 's/^[[:space:]]*\([0-9a-f]\{40\}\)$/\1/p' | sed -n '1p')" -[[ "$readme_pin" == "$current_release_commit" ]] || { - printf 'README current-release pin does not match the expected v2.1.0 commit.\n' >&2 +[[ "$readme_pin" == "$quickstart_release_commit" ]] || { + printf 'README current-release pin does not match the v2 quickstart commit.\n' >&2 exit 1 } -if resolved_current_release="$(git rev-parse --verify "${readme_current_release}^{commit}" 2> /dev/null)"; then +if resolved_current_release="$(git rev-parse --verify "${current_release}^{commit}" 2> /dev/null)"; then [[ "$resolved_current_release" == "$readme_pin" ]] || { printf 'README current-release pin does not match its tag.\n' >&2 exit 1 } else - printf 'Skipping README current-release tag comparison: tag %s is unavailable in this checkout.\n' \ - "$readme_current_release" >&2 + printf 'Skipping current-release tag comparison: tag %s is unavailable in this checkout.\n' \ + "$current_release" >&2 fi grep -F 'framework_launcher' docs/v2/quickstart.md > /dev/null || { printf "The v2 quickstart must use the verified launcher path.\n" >&2