- beads-release formula: drop the snapshot-docs step (ran the deleted scripts/snapshot-release-docs.sh on the critical needs-chain); stamp- changelog now needs update-vendorhash - update-versions.sh: remove the mangled --skip-docs/docs-snapshot logic and garbled usage text left by mid-line deletions - pre-push hook: drop the snapshot-script remediation hint - release.yml: collapse the prerelease branch; BEADS_REQUIRE_RELEASE_DOCS has no consumer since check-docs-version.sh was deleted - RELEASING.md / scripts/docs.md: describe the current pipeline (no --versioned, no website/ outputs, no check-docs-version.sh) - docs-mintlify.yml: paths filter now includes engdocs/** and the curated root markdown files the docsync guard validates - docs-render-check.sh: pin mint@4.2.687, fail closed when mint dies without producing a broken-links report, parse report lines only, drop dead extract_page_links(), fix the stale jq requirement; mint.sh pins the same version - nightly.yml: remove the deleted website measurement suite option - CODEOWNERS: init-safety ADR gate follows the file to engdocs/adr/ - beads-docs skill: align with settled decision 6 — no pointer stubs, moved pages get docs.json redirects; bd's printed paths are fixed at the source - CHANGELOG (edited line), FEDERATION-SETUP, README, examples, oracle-a, .buildflags, gh-issue-to-pr formula: retarget moved-file references; anchor the build/ gitignore pattern
7.4 KiB
Noridoc: scripts
Path: @/scripts
Overview
The scripts directory contains build and release automation utilities for the beads project. These scripts handle version management, installation with embedded build info, and release orchestration across multiple distribution channels.
Key scripts include version bumping, installation helpers that inject git information at build time, and release coordination across GitHub, Homebrew, PyPI, and npm.
generate-cli-docs.sh
Generates maintained CLI reference docs from the live Cobra command tree in
two stages: bd help --docs-root emits vendor-neutral output (the single-file
reference plus a generic per-command tree in uncommitted staging), then
tools/docsmint post-processes the staging tree into the committed Mintlify
pages and splices the CLI Reference pages array in docs/docs.json.
Usage
# Regenerate checked-in CLI docs using a temporary no-cgo build
./scripts/generate-cli-docs.sh
# Regenerate/check against an existing binary
./scripts/generate-cli-docs.sh ./bd
./scripts/generate-cli-docs.sh --check ./bd
Outputs
docs/CLI_REFERENCE.mdfrom the live Cobra command treedocs/cli-reference/*.md(Mintlify pages) viatools/docsmint- the CLI Reference pages array in
docs/docs.json
scripts/check-cli-docs-drift.sh runs the --check mode in CI and fails when
the committed copies are stale relative to the live command tree.
check-doc-freshness.sh
Validates marker-based freshness for reference-shaped docs that are not generated from a single clean source.
Usage
./scripts/check-doc-freshness.sh
make check-docs
The script currently checks the reference docs named in engdocs/DOC_INVENTORY.md: CONFIG.md, SETUP.md, ADO_CONFIG.md, JSON_SCHEMA.md, RECOVERY.md, ERROR_HANDLING.md, LINTING.md, and design/otel/otel-data-model.md. Each doc must be listed in the inventory, include a recent Last reviewed: marker, include a Freshness source: marker, and name source paths or globs that exist in the repository.
Set DOC_FRESHNESS_MAX_AGE_DAYS to override the default 90-day review window. Set DOC_FRESHNESS_TODAY=YYYY-MM-DD when testing date behaviour.
How it fits into the larger codebase
-
Build Integration: The
install.shscript is referenced in documentation and release processes as the primary user-facing installation mechanism. It integrates directly with the Go build system to ensure full version information is embedded. -
Version Pipeline: Works alongside the version infrastructure in
@/cmd/bd/version.goby extracting and passing git information at build time via ldflags. -
Release Automation: The
release.shandbump-version.shscripts orchestrate the release process documented in@/RELEASING.md, ensuring version consistency across all components (CLI, plugin, MCP server, npm package). -
CI/CD Integration: Goreleaser (configured in
@/.goreleaser.yml) uses the same ldflag patterns established by these scripts, ensuring consistency across all installation methods. -
Multi-Channel Distribution: These scripts ensure that whether a user installs via Homebrew, npm, GitHub releases, or direct
go install, they get consistent version reporting with full git information.
Core Implementation
install.sh (GitHub issue #503 fix):
The script simplifies local installation from source while ensuring full version information is available in the resulting binary:
-
Usage (lines 1-6):
- Can be invoked from source checkout with optional custom install directory
./scripts/install.shinstalls to$(go env GOPATH)/bin./scripts/install.sh /usr/local/bininstalls to custom location
-
Git Information Extraction (lines 12-14):
- Extracts full commit hash via
git rev-parse HEAD - Extracts branch name via
git rev-parse --abbrev-ref HEAD - Gracefully handles missing git info (returns empty strings in non-git environments)
- Extracts full commit hash via
-
Build Information Display (lines 16-18):
- Shows user where installation will occur
- Displays the 12-character short commit hash
- Displays the branch name for context
-
Installation with Ldflags (line 20):
- Calls
go installwith explicit-ldflagsto setmain.Commitandmain.Branch - These ldflags inject values that are then picked up by
resolveCommitHash()andresolveBranch()in@/cmd/bd/version.go
- Calls
-
Post-Install Verification (lines 22-24):
- Immediately runs
bd versionto show the user that installation succeeded - User sees commit and branch info in the output, confirming full version info is present
- Immediately runs
Makefile Integration (@/Makefile, lines 37-41):
The Makefile's install target uses identical logic:
- Extracts git info at build time
- Passes to
go installvia ldflags - Ensures that standard
make installproduces binaries with full version info, not justmake build
Goreleaser Configuration (@/.goreleaser.yml):
All 5 platform builds (linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64) use goreleaser's built-in git variables:
-X main.Commit={{.Commit}}uses goreleaser's detected commit-X main.Branch={{.Branch}}uses goreleaser's detected branch- Ensures released binaries have full version info without requiring manual extraction
Version Bumping (bump-version.sh and release.sh):
- Coordinates version updates across multiple files (CLI version, plugin metadata, MCP server, npm package)
- Ensures all distribution channels report consistent version numbers
- Integrates with release process documented in
@/RELEASING.md
Things to Know
Why Explicit Ldflags Are Necessary:
go installdoes not automatically embed VCS information likego builddoes (even though Go supports it)- Without explicit ldflags, binaries lack commit and branch information regardless of installation method
- The Makefile and goreleaser configurations compensate for this limitation
Installation Path Resolution:
- The script uses
$(go env GOPATH)/binas the default installation target - This respects the user's Go configuration and matches standard Go tooling behavior
- Allows overriding for system-wide installations (e.g.,
/usr/local/bin)
Git Information Fallbacks:
- The script silently handles missing git info (returns empty strings)
- This allows installation in non-git environments or git-less distributions
- The version command in
@/cmd/bd/version.gohas its own fallback chain
Testing the Version Pipeline:
- After running
./scripts/install.sh, users should immediately see full version info viabd version - The text output shows format like:
bd version 0.29.0 (dev: main@7e70940) - JSON output includes both
commitandbranchfields
Release Coordination:
- The
install.shscript is independent of release automation - Users can run it locally to build from any source branch
- Release scripts (
release.sh,update-homebrew.sh) handle orchestration across channels and are documented separately in@/RELEASING.md
Platform Compatibility:
- All scripts use POSIX shell constructs (bash on all platforms)
- Git operations work identically on macOS, Linux, and Windows (with Git for Windows)
- The go install command behaves consistently across all platforms
Security Considerations:
- Scripts use
set -eto fail fast on any errors - Git commands are defensive (using
2>/dev/nullto suppress errors) - No shell injection risks as git values are passed as structured arguments
Created and maintained by Nori.