From 20a7d4973a0d04076726ff3bf3ced028311207fa Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Thu, 8 Oct 2026 11:18:08 +0530 Subject: [PATCH] docs: link Beacon as the v2 learning path --- CHANGELOG.md | 5 ++++- README.md | 13 +++++++++---- docs/README.md | 4 ++++ docs/consumer-validation-status.md | 2 +- docs/v2/quickstart.md | 9 +++++++++ tests/docs-contract.sh | 22 ++++++++++++++++++++++ 6 files changed, 49 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb90683..84737ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,10 @@ and versions are tracked in the repo-root `VERSION` file. ## [Unreleased] -No unreleased changes yet. +### Documentation + +- Link the pinned Base Bash Demo v0.1.2 learning path from the README, + documentation index, and v2 quickstart, and refresh the consumer ledger. ## [2.2.1] - 2026-10-08 diff --git a/README.md b/README.md index 71374eb..4921e08 100644 --- a/README.md +++ b/README.md @@ -71,10 +71,15 @@ Production-shaped reference applications and transparent startup benchmarks are in [`examples/reference-apps`](examples/reference-apps) and [`benchmarks/reference-apps.sh`](benchmarks/reference-apps.sh). The isolated first-party -[`base-bash-libs-demo`](https://github.com/basefoundry/base-bash-libs-demo) -repository consumes the canonical release bundle and runs its Beacon -application as a downstream compatibility canary. It is regression evidence, -not an independent-adoption claim. +[`base-bash-libs-demo`](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/README.md) +repository is a five-minute, offline Beacon application that shows the v2 +CLI, configuration, lifecycle, and cleanup contracts in a complete consumer. +Start with its [pinned five-minute tutorial](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md), +then read [why Base Bash](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md) +and the [adoption decision guide](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md). +The repository also consumes the canonical release bundle as a downstream +compatibility canary. It is regression evidence, not an independent-adoption +claim. For the rest of the documentation, use the map near the end of this README. ## When to reach for Base Bash diff --git a/docs/README.md b/docs/README.md index 178e4bc..f91e2ed 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,10 @@ when updating an existing script. ## Start here - [Five-minute quickstart](v2/quickstart.md) +- [Beacon reference consumer](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/README.md): a complete, offline application walkthrough + using the released v2 API. Continue with the [five-minute tutorial](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md), + [why Base Bash](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md), + and the [adoption decision guide](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md). - [Architecture and execution model](v2/architecture.md) - [API reference](api-reference.md) and [v2 API contract](v2-api-contract.md) - [Configuration, lifecycle, and status contracts](v2/architecture.md#application-contract) diff --git a/docs/consumer-validation-status.md b/docs/consumer-validation-status.md index e220630..4a92911 100644 --- a/docs/consumer-validation-status.md +++ b/docs/consumer-validation-status.md @@ -42,7 +42,7 @@ results count as independent adoption evidence. | --- | --- | --- | --- | --- | --- | | 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 | released [v0.1.0](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.0) at `7acf3c6`; docs and vendor target the verified v2.2.0 bundle while the v2.2.1 upstream patch is prepared | 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 | +| Base Bash Demo | First-party isolated reference consumer | released [v0.1.2](https://github.com/basefoundry/base-bash-libs-demo/releases/tag/v0.1.2) at `ab4da09`; docs and vendor target the verified v2.2.0 bundle while v2.2.1 is the current upstream release | 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 for the v0.1.2 release preparation | 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/v2/quickstart.md b/docs/v2/quickstart.md index dababb2..5a3af44 100644 --- a/docs/v2/quickstart.md +++ b/docs/v2/quickstart.md @@ -78,3 +78,12 @@ their caller-relative meaning. The complete process is also available offline in the [`tests/consumer-kit`](../../tests/consumer-kit/README.md) fixture. + +## 4. See a complete application + +For a consumer that applies these contracts to a small offline application, +continue with [Beacon's pinned five-minute tutorial](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md). +Then read [why Base Bash](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md) +and the [adoption decision guide](https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md). +This is a first-party reference consumer and compatibility canary, not an +independent-adoption claim. diff --git a/tests/docs-contract.sh b/tests/docs-contract.sh index 79c3db0..91d5bea 100755 --- a/tests/docs-contract.sh +++ b/tests/docs-contract.sh @@ -80,6 +80,28 @@ grep -F 'v2/quickstart.md' docs/README.md > /dev/null || { printf 'Documentation link is missing: v2/quickstart.md\n' >&2 exit 1 } +for demo_contract_url in \ + 'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/README.md' \ + 'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/five-minute-tutorial.md' \ + 'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/why-base-bash-libs.md' \ + 'https://github.com/basefoundry/base-bash-libs-demo/blob/v0.1.2/docs/should-i-use-base-bash-libs.md'; do + grep -R -F "$demo_contract_url" README.md docs/README.md docs/v2/quickstart.md > /dev/null || { + printf 'Pinned Beacon learning-path link is missing: %s\n' "$demo_contract_url" >&2 + exit 1 + } +done +grep -F 'five-minute, offline Beacon application' README.md > /dev/null || { + printf 'README must describe Beacon as a runnable learning path.\n' >&2 + exit 1 +} +grep -F 'See a complete application' docs/v2/quickstart.md > /dev/null || { + printf 'The v2 quickstart must link to the complete Beacon application.\n' >&2 + exit 1 +} +grep -F 'released [v0.1.2]' docs/consumer-validation-status.md > /dev/null || { + printf 'Consumer validation status must reference the current Beacon release.\n' >&2 + exit 1 +} grep -F 'v2/architecture.md' docs/README.md > /dev/null || { printf 'Documentation link is missing: v2/architecture.md\n' >&2 exit 1