diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..097c0a3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# Agent Guidance + +Read [CONTRIBUTING.md](CONTRIBUTING.md) for the issue, worktree, pull request, +validation, and cleanup workflow. Read [STANDARDS.md](STANDARDS.md) before +changing the shell libraries. + +## Release Work + +Read [docs/release-process.md](docs/release-process.md) before doing release +work. Ordinary pull requests must leave `VERSION` unchanged; a release-prep +pull request owns the version, README release row, and changelog transition. + +The repository release contract is declared in `base_manifest.yaml`. Use the +guarded `basectl release check|plan|notes|publish` commands after the release +preparation pull request is merged, and complete the Homebrew and Base +downstream handoffs documented in the release process. + +## Shell Changes + +- Keep each public sourceable library in its single-file boundary. +- Do not add `set -e`, `set -u`, or `set -o pipefail` to production libraries. +- Add focused BATS coverage for behavior changes and run `./tests/validate.sh`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f01c6b..7ea0ea7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,10 @@ repository inherits Base's shell-library standards, including the convention that each sourceable shell library remains a single file at its library boundary. +For release work, read [docs/release-process.md](docs/release-process.md). The +repository release contract is declared in `base_manifest.yaml`; ordinary pull +requests leave `VERSION` unchanged. + ## Workflow 1. Create or choose a GitHub issue before starting implementation work. diff --git a/README.md b/README.md index 6cb2905..fea60ce 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,10 @@ 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. +Release preparation and downstream Homebrew/Base handoffs are documented in +[`docs/release-process.md`](docs/release-process.md). The machine-readable +release contract lives in [`base_manifest.yaml`](base_manifest.yaml). + ## License base-bash-libs is licensed under [Apache-2.0](LICENSE). See [NOTICE](NOTICE) for diff --git a/base_manifest.yaml b/base_manifest.yaml index 3ff4ce0..8fe1cd4 100644 --- a/base_manifest.yaml +++ b/base_manifest.yaml @@ -5,3 +5,18 @@ project: test: command: ./tests/validate.sh + +release: + version_file: VERSION + changelog: CHANGELOG.md + tag_prefix: v + github: + repository: basefoundry/base-bash-libs + release_title: "base-bash-libs v{version}" + homebrew: + required: true + tap_repository: basefoundry/homebrew-base + formula_path: Formula/base-bash-libs.rb + package: basefoundry/base/base-bash-libs + +artifacts: [] diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 0000000..831ab4c --- /dev/null +++ b/docs/release-process.md @@ -0,0 +1,78 @@ +# base-bash-libs Release Process + +This repository declares its release contract in +[`base_manifest.yaml`](../base_manifest.yaml). It is consumed by Base's guarded +release commands and is the source of truth for the version file, changelog, +GitHub Release, and Homebrew handoff. + +## Standard Sequence + +1. Create or choose a release issue and set its repository Project metadata. +2. Create a release-preparation branch and dedicated worktree from + `origin/main`. +3. Move the relevant `Unreleased` entries in `CHANGELOG.md` into a dated + release section. Update `VERSION` and the top release row in `README.md` to + the same version. Ordinary pull requests do not change `VERSION`. +4. Run the full library validation and inspect the diff: + + ```bash + ./tests/validate.sh + git diff --check + ``` + +5. Open and merge the release-preparation pull request. +6. Sync local `main`, then inspect the release from the repository root: + + ```bash + basectl release check --version X.Y.Z --manifest base_manifest.yaml + basectl release plan --version X.Y.Z --manifest base_manifest.yaml + basectl release notes --version X.Y.Z --manifest base_manifest.yaml + basectl release publish --version X.Y.Z --manifest base_manifest.yaml --dry-run + ``` + +7. Publish only after the readiness checks pass. Use `--yes` only from a + trusted non-interactive release shell: + + ```bash + basectl release publish --version X.Y.Z --manifest base_manifest.yaml --yes + ``` + +8. Verify the annotated `vX.Y.Z` tag and the GitHub Release for + `basefoundry/base-bash-libs`. + +## Homebrew Handoff + +The release contract requires the tap-owned formula +`basefoundry/base/base-bash-libs` in `basefoundry/homebrew-base`. + +After the GitHub Release exists: + +1. Create a tap release branch and update `Formula/base-bash-libs.rb` to the + new archive URL, version, SHA256, and version assertions in the formula test. +2. Validate the formula from the tap checkout: + + ```bash + brew install --build-from-source Formula/base-bash-libs.rb + brew test basefoundry/base/base-bash-libs + brew audit --new --formula Formula/base-bash-libs.rb + ``` + +3. Publish any tap bottle artifacts required by the tap policy, then open and + merge the tap pull request. +4. Smoke-test a consumer install and verify that `BASE_BASH_LIBS_VERSION` and + the `base-bash` launcher report the new version. + +## Base Handoff + +Base pins this repository by full commit SHA in its GitHub Actions workflows. +After the release, update the Base pin to the release commit, run Base's +source-checkout and integration tests, and record the dependency update in the +Base changelog when it is user-visible or release-relevant. + +## Finish + +Record the library release URL, Homebrew tap pull request, and Base dependency +pull request on the release issue. Remove the release worktree and merged +branches when safe. Do not publish a release while the worktree is dirty, the +version metadata disagrees, the changelog section is missing, or a declared +downstream handoff has not been completed or explicitly deferred.