Repository navigation
Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract #240
Description
Parent: #214
Train position: 25 of 26
Phase: P3 — Ecosystem trust and broad adoption
Problem
The v2 framework is intentionally incompatible with the 1.x API, but first-party consumers and distribution are coupled today: Base accepts only compatible 1.* libraries, Base and Base Demo pin v1.4.0 and v1.3.0 release commits in CI, and Homebrew's unversioned Base formula depends on the latest base-bash-libs formula. Publishing the v2 formula before a compatible Base release would break existing Homebrew Base installations.
Acceptance criteria
- Inventory every first-party API use, version gate, full-SHA pin, fixture, workflow, formula, bottle, active document, and release contract across
base,base-demo,homebrew-base, and every other Basefoundry repository discovered before cutover. - Migrate Base from its current
case 1.*/ minimum 1.3.0 gate and legacy function names to an explicit supported v2 contract, with no dependency on compatibility aliases. - Update every Base CI pin, Base Demo's Base and
base-bash-libspins, validators, fixtures, messages, documents, and end-to-end tests to the exact verified v2 artifact and compatible Base release. - Update Homebrew to the canonical v2.0.0 GA release asset—not the previously used automatic tag-archive URL—plus its checksum, version assertions, and bottles while retaining
version_scheme 1; update and bottle the dependent Base formula in the same tap change so no stable formula combination exposes Base 1.x code to v2 libraries. - Validate source-checkout, Homebrew, vendor, and bundle paths against the same v2 release candidate on supported macOS and Linux environments.
- Document and rehearse the publish order: v2 RC validation; Base migration and release preparation; base-bash-libs v2.0.0 GA; compatible Base release; atomic tap formula and bottle promotion; Base Demo pin and release update.
- Document a rollback that moves the tap formulas and first-party pins back as compatible pairs without deleting, moving, or reusing published tags.
- Remove stale active references to “compatible later 1.x,” the 1.3.0 minimum, v1.4.0/v1.3.0 pins, and pre-v2 API assertions.
- Prove the coordinated cutover with green release, integration, and upgrade checks and record links to every cross-repository PR and release in this issue.
Dependencies
- Establish the v2.0.0 release line and enforce trustworthy version invariants #215
- Namespace public functions and globals for safe embedding #223
- Standardize public error, status, output, and mutation semantics #224
- Unify imports, version provenance, and pinned consumption #226
- Make base-bash a conventional, stable application launcher #227
- Ship pinned bundle, vendor, update, and verified release workflows #233
- Establish full Bash, OS, strict-option, and supply-chain release gates #234
- Publish stability, support, security, and deprecation policies #235
- Launch versioned documentation with a five-minute adoption path #236
- Publish official generator, testing, and package-manager integrations #237
- Ship production-grade reference applications and transparent benchmarks #238
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
[-]Migrate first-party consumers and Homebrew to the Base Bash 3.0 contract[/-][+]Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract[/+]ci(cutover): add first-party v2 release handoff checks (#240) (#271)
codeforester commentedon Aug 6, 2026
Status update after the engineering train:
basectl helppath passes the focused and full Base tests.first-party-cutover.yamlremains intentionallyrelease_status: pending-ga-asset; Base Demo and Homebrew are unchanged until a canonical v2.0.0 asset, checksum, and provenance exist.The remaining acceptance items are the real GA asset/tag, downstream Base Demo/Homebrew updates, rollback rehearsal, and cross-repository verification.
docs(cutover): record merged Base migration status (#240) (#276)
ci: rehearse Base Bash v2 pins (#213)
codeforester commentedon Aug 14, 2026
Progress update (2026-08-14): the first consumer-side v2 cutover rehearsal is complete.
Remaining #240/#215 gates are still real: publish the canonical v2.0.0 RC/GA asset with checksum, provenance, and SBOM; rehearse rollback; then update Base Demo and Homebrew to the canonical GA asset and complete cross-repository verification.
codeforester commentedon Aug 14, 2026
Follow-up: #215 PR #321 is merged at
290e4e6. The repository now has a deterministic, cross-platformscripts/release-artifactbuilder/verifier that emits the canonical archive, SPDX 2.3 SBOM, provenance statement, and checksum manifest, with hosted Ubuntu/macOS validation green.This advances the artifact-generation gate but does not publish v2.0.0 or change Homebrew. The remaining cutover work is still the immutable RC/GA promotion, rollback rehearsal, canonical Homebrew asset/formula update, and final Base/Base Demo cross-repository proof.
codeforester commentedon Aug 15, 2026
RC cutover and rollback rehearsal (2026-08-15)
Completed the pre-GA consumer rehearsal against `v2.0.0-rc.1` at commit
`c134fb8a3397e2cfee1d90845cec44f56dacae7b`:
Stable Homebrew was not changed because RC is not GA. The eventual v2 formula
must consume the deterministic bundle layout and use the `base_` API; the
v1.4 formula's source-archive assumptions are intentionally deferred to the GA
handoff. Evidence ledger PR: #326.
docs: record v2 RC consumer and rollback evidence
docs: record completed first-party v2 cutover (#329)
codeforester commentedon Aug 15, 2026
First-party v2.0.0 cutover complete\n\nThe release train is complete and the evidence ledger is merged in PR #329.\n\n-
base-bash-libsv2.0.0: release, GA commitb4243765726c133499feeabdc50154f99c0fec12, canonical archive SHA25673d6f92fab8f1a8ded7f3b4312ebbe51aa8ec0c16eacf18c2d8fa23fb5664333.\n- Base: PR #1936 merged; v1.8.0 release at commit26b9af5dee16efcb47e652513ce734b3ae9bc920; tracker Base #1935 is closed.\n- Base Demo: PR #217 merged atfb7a2b6fa662f9f6d2c91b522a183af1cebbaae1; tracker #215 is closed.\n- Homebrew: PR #85 merged; bottle releasebase-v1.8.0published with Base 1.8.0 and base-bash-libs 2.0.0 bottles. Workflow run 31872508249 passed bottle builds, v2 API smoke tests, formula tests, and the controlled upgrade/rollback rehearsal.\n\nThe remaining 5/5 gate is #239: independent external adoption and a second maintainer/community review.