checks.nix's hook-timeout-backends (the tracked git hook shims against real GNU/uutils/busybox/toybox timeout implementations, with and without perl, under dash, bash and busybox ash: 240 cases) was the one test PR Risk's test-nix ran on a GitHub runner, through `nix flake check`. It is now //tests/hook_timeout_backends:hook_timeout_backends_test, an sh_test (pr-core-only) that the bazel-test lane runs remotely on every PR: the static uutils 0.12.0, busybox 1.35.0 and toybox 0.8.15 binaries come in sha256-pinned through MODULE.bazel; dash, bash, perl and GNU coreutils from the executor, failing (not skipping) when one is missing. checks.nix goes and flake.nix declares no checks, so test-nix's `nix run .#default` + `nix flake check` is a packaging check (build the package Nix users install, evaluate every flake output), not a test. TestHookTimeoutBackendsRunUnderBazel pins the target and that no flake check comes back. ga-96smfk.22 Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
18 KiB
Contributing to bd
Thank you for your interest in contributing to bd! This document provides guidelines and instructions for contributing.
Issues and pull requests
GitHub Issues is the public tracker. Use an issue when it adds context reviewers need: a user-visible bug, a behavior or design change worth discussing first, or work that spans several pull requests. The issue holds why the change is needed, what it affects, and how we will know it works; file it with the bug or feature form before or alongside your pull request, and it does not need maintainer approval first. Small, self-explanatory changes (typos, flaky tests, refactors, CI or docs tweaks) can go straight to a pull request whose description explains the why.
Triage labels
| Label | Meaning | Applied by |
|---|---|---|
status/needs-triage |
Awaiting initial triage. | Automation, on every new issue |
status/needs-info |
Waiting on essential information from the reporter. | Maintainers |
status/needs-repro |
Needs a reproducible bug report. | Maintainers |
status/needs-design |
The direction needs a design decision before work starts. | Maintainers |
status/accepted |
Confirmed and on our radar. | Maintainers |
Issues left in status/needs-info or status/needs-repro are closed after 14
days without a reply to the request; reply with the details and a
maintainer will reopen them.
Priority (priority/p0–priority/p3) and kind (kind/bug, kind/feature,
kind/docs, kind/chore) labels are set during triage.
Pull request pipeline labels
These labels drive the maintainers' automated review and merge workflow. They are applied by maintainers and automation; contributors don't need to set them.
| Label | Meaning |
|---|---|
status/needs-review |
Request the PR review workflow. |
status/needs-review-auto |
Request the automated PR review workflow. |
status/reviewing |
The PR review workflow is running. |
status/review-failed |
The PR review workflow failed before merge-ready. |
status/merge-ready |
The PR is ready for the merge workflow. |
status/merge-queued |
Queued for deterministic PR-review merge. |
status/merge-failed |
The merge queue needs operator attention. |
status/needs-bugflow |
Request the bugflow investigation workflow. |
The current priorities are on the roadmap; work in a priority area is reviewed first.
Development Setup
Prerequisites
- Bazelisk, installed as
bazel(it reads.bazelversion). Required: Bazel is the build and test system CI gates on, and the pre-commit (nogo lint) and pre-push (test suite) hooks run it. - Go (see
go.modfor the required version; currently 1.26+), formake installand thego testinner loop - Git
- A C compiler (CGO is required for the embedded Dolt database)
- ICU headers are not required for building -- see engdocs/ICU-POLICY.md
Getting Started
# Clone the repository
git clone https://github.com/gastownhall/beads
cd beads
# Read rbe-west's anonymous, read-only cache: everything CI already built and
# tested is a cache hit, and nothing you build is uploaded.
echo 'build --config=fork-cache' >> .bazelrc.local
# Run the test suite CI gates on (bazel test //... --config=ci)
make test
# Build and install bd to ~/.local/bin (also enables the git hooks)
make install
Building and Testing
Bazel is the gate: .github/workflows/bazel.yml runs every pull request's
tests as bazel test lanes, and nogo (lint + vet), gofmt and the repository
guards exist only as Bazel targets. The make targets run the same commands:
| Command | Runs |
|---|---|
make test |
bazel test //... --config=ci: the test lane (unit tests, nogo, gofmt, repository guards) |
make check |
the testing.Short policy, make ci-pr-lint and make test |
make ci-pr-lint |
nogo natively plus the windows/amd64 and darwin/arm64 passes |
make check-docs |
the Bazel docsync and doc-freshness tests, then the CLI flag check |
bazel test //... --config=integration |
the integration lane; engdocs/TESTING.md lists every other lane's command |
Where actions run is your choice, set in the gitignored .bazelrc.local (or
per command with make test BAZEL_FLAGS=--config=...):
--config=fork-cache(contributors): reads the anonymous cache, runs misses on your machine, uploads nothing.--config=remote-exec(maintainers with an rbe-west client certificate): executes remotely; the executor and TLS lines stay in youruser.bazelrcor.bazelrc.local.
go test (./scripts/test.sh, or make test-go / make check-go /
make check-docs-go) still works as an inner-loop convenience, but CI does not
enforce it and it skips nogo, gofmt and the guards. Finish with make test.
Project Structure
beads/
├── cmd/bd/ # CLI entry point and commands
├── internal/
│ ├── types/ # Core data types (Issue, Dependency, etc.)
│ └── storage/ # Storage interface and implementations
│ └── dolt/ # Dolt database backend
├── .golangci.yml # Linter configuration (applied by nogo, tools/nogo)
└── .github/workflows/ # CI/CD pipelines
Running Tests
Use the canonical testing guide to choose focused tests, the proportional validation budget, and any applicable CI wrapper. The setup and safety notes in this file supplement that guide; they do not define a second test policy.
Code Style
We follow standard Go conventions:
- Use
gofmtto format your code (runs automatically in most editors) - Follow the Effective Go guidelines
- Keep functions small and focused
- Write clear, descriptive variable names
- Add comments for exported functions and types
Linting
Lint and vet run as nogo under Bazel: go test's vet checks plus the
golangci-lint linters .golangci.yml enables, the same analyzers CI gates on.
# Run the required lint and vet gate (native, windows and darwin)
make ci-pr-lint
# Faster: only the Bazel packages of your changed Go files
make lint-changed
make ci-pr-lint must pass with zero issues. It analyzes the repository's
normal gms_pure_go build and cross-checks the Windows- and macOS-only
non-cgo code. Accepted intentional patterns are encoded narrowly in
.golangci.yml; do not ignore a failing baseline. See
engdocs/LINTING.md for the full policy.
CI runs the same analyzers on all pull requests, in the Bazel test lane.
Making Changes
Project Scope
Before adding new feature surface area, read engdocs/PROJECT_CHARTER.md. Beads owns issue tracking primitives. It should not encode orchestration-layer policy, become a storage engine, or expand the database schema when issue metadata is sufficient.
Workflow
- If the change warrants one, find or file an issue (see Issues and pull requests)
- Fork the repository and create a feature branch (
git checkout -b feature/my-feature) - Make your changes
- Add tests for new functionality
- Run tests and linter locally
- Commit your changes with clear messages
- Push to your fork
- Open a pull request that explains the change and says
Closes #<issue>when there is one
Commit Messages
Use Conventional Commits:
type(scope): summary, where type is one of fix, feat, docs, test,
refactor, chore, ci, or perf.
feat(dep): add cycle detection for dependency graphs
- Implement recursive CTE-based cycle detection
- Add tests for simple and complex cycles
- Update documentation with examples
Pull Request Hygiene
One issue per PR, and one PR per issue. No piggybacking or riders — each PR should address exactly one thing.
Read CONTRIBUTING_PR_GUIDELINES.md for the layering rules (schema → storage/issueops → cmd/bd, one layer per PR) and the repro and benchmark evidence reviewers expect.
- Keep PRs focused on a single feature or fix
- Do not include unrelated changes, cleanup, or "while I'm here" improvements
- Do not include
.beads/data (database, JSONL) in your PR - Make sure there are no extra generated or garbage files in your diff
- Include tests for new functionality
- Update documentation as needed
- Ensure CI passes before requesting review
- Respond to review feedback promptly
- Lead the PR with a brief plain-language
WhatandWhyso reviewers can grasp the goal without reading the diff..github/PULL_REQUEST_TEMPLATE.mdis a starting scaffold — replace, expand, or delete sections to fit your change.
ZFC (Zero Framework Cognition)
If you are contributing code that involves AI decision-making or orchestration, understand and follow the ZFC principles. In short: keep the smarts in the AI models, keep the code as dumb orchestration. Do not add heuristics, keyword matching, ranking logic, or semantic analysis in application code — delegate cognitive decisions to AI.
Testing Guidelines
For test commands, test design, and PR-readiness gates, see the canonical engdocs/TESTING.md.
Before Opening a PR
- Follow the proportional validation budget in
engdocs/TESTING.md: docs-only changes use docs checks;
Go changes use focused and affected-package tests plus one final
make test(the Bazel test lane). - If you hit a test failure unrelated to your change, don't silently skip
it -- check
.test-skipand file an issue if it's not already tracked (see engdocs/TESTING.md). - Run a named CI wrapper only when its risk or surface is affected, or when reproducing that CI check.
- If your change touches ICU or build tags, see engdocs/ICU-POLICY.md for the policy and rationale.
Documentation
- Update README.md for user-facing changes
- Update relevant .md files in the project root
- Add inline code comments for complex logic
- Include examples in documentation
Storage filter conventions
IssueFilter.MaxRows opt-out rule (be-x42v)
types.IssueFilter carries a defensive row cap (MaxRows int,
MaxRowsSource string) that the storage layer enforces via
*issueops.ErrTooManyRows. The cap is wired from --max-rows /
BEADS_MAX_ROWS on user-facing commands listed in designer §4 of be-x42v
(bd list, bd ready, bd dep tree, bd find-duplicates, bd graph,
plus env-only on the doctor family).
Rule for new code that builds an IssueFilter: if your call site is
NOT on the designer's wired-up list, you MUST explicitly initialize
filter.MaxRows = 0 and filter.MaxRowsSource = "". This makes the
opt-out intentional in code review and survives future refactors that
might otherwise let the env var leak into a sweep path that must not
abort (export, gc, jira sync, migrate-issues, etc.).
The opt-out test gates (be-x42v.4) enforce this for the export / migrate / jira / cleanup / gc paths today. New write-side or round-trip paths should pattern-match on those tests.
Feature Requests and Bug Reports
Use the issue forms: bug report or feature request. The feature form asks for the motivation, impact, risk and compatibility, and verification plan up front, so a maintainer can accept the issue without a round trip. Questions go to Discussions.
Your PR Will Not Be Overwritten
This project uses AI agents for maintenance. We've established strict rules to protect contributor work:
- Your PR has priority. If you've submitted a PR, agents must review and build on your work — not rewrite it from scratch.
- Your tests matter. Agents must preserve contributor tests unless they're actually wrong.
- You'll get attribution. Your commits and
Co-authored-by:will be preserved. - No silent closes. Your PR will never be auto-closed by a parallel rewrite. If changes are needed, they'll be discussed on your PR.
If any of this goes wrong, please open an issue — we take contributor experience seriously.
Maintainers and agents follow PR_MAINTAINER_GUIDELINES.md when triaging, landing, transforming, or closing PRs.
Refactoring Campaign PR Intake Checklist
Before starting a rewrite, cleanup, or large refactoring pass, maintainers and agents must review open contributor PRs that touch the same area. Use this checklist to decide whether to merge, rebase, incorporate, or close each PR.
-
Identify overlap:
- Read the PR description, changed files, linked issues, and latest review comments.
- Compare the PR scope with the planned refactor and note any shared files, commands, migrations, tests, docs, or release paths.
- If the PR is unrelated, leave it alone unless the refactor would still create a merge conflict.
-
Prefer clean merges:
- If the PR is focused, passing CI, and aligned with current design, review it as the first option.
- Merge it before the refactor when that reduces conflict risk.
- Preserve the contributor's commits and attribution unless the contributor agrees to a squash or rework.
-
Request a rebase when needed:
- Ask for a rebase if the PR is still valid but conflicts with main or depends on code that has moved.
- Give concrete instructions about the new target files or APIs.
- Do not rewrite the same work in parallel while waiting unless there is a release blocker or security issue.
-
Preserve tests and intent:
- Treat contributor tests as part of the contribution, not optional scaffolding.
- If a refactor supersedes implementation code, port the tests or explain why they are invalid.
- Keep user-facing behavior, docs examples, and regression coverage intact unless the PR is explicitly changing the contract.
-
Close superseded PRs with explicit rationale:
- Close only after commenting with the replacement commit, PR, or issue.
- Explain what was preserved, what changed, and why the original branch will not be merged.
- Thank the contributor and invite follow-up if their use case was not fully covered.
-
Leave an audit trail:
- Link the intake decision from the refactor PR or Beads issue.
- Record any follow-up work as Beads issues instead of hidden notes.
- Call out contributor-owned tests or behavior in the refactor PR summary.
Code Review Process
All contributions go through code review:
- Automated checks (tests, linting) must pass
- At least one maintainer approval required
- Address review feedback
- Maintainer will merge when ready
Development Tips
Testing Locally
# Build and install your changes
make install
# Test specific functionality
bd init --prefix test
bd create "Test issue" -p 1 -t bug
bd dep add test-2 test-1
bd ready
Database Inspection
# Inspect the Dolt database directly
bd query "SELECT * FROM issues"
bd query "SELECT * FROM dependencies"
bd query "SELECT * FROM events WHERE issue_id = 'test-1'"
Updating Nix flake.lock (without nix installed)
The flake.lock file pins a specific nixpkgs revision. When go.mod bumps the Go version beyond what's in the pinned nixpkgs, the Nix CI job will fail. To update flake.lock without installing nix locally, use Docker:
# Update flake.lock
docker run --rm -v $(pwd):/workspace -w /workspace nixos/nix \
sh -c 'echo "experimental-features = nix-command flakes" >> /etc/nix/nix.conf && nix flake update'
# Verify the build works
docker run --rm -v $(pwd):/workspace -w /workspace nixos/nix \
sh -c 'echo "experimental-features = nix-command flakes" >> /etc/nix/nix.conf && nix build .#default && ./result/bin/bd version'
If the build fails with a vendorHash mismatch, run ./scripts/update-nix-vendorhash.sh to recompute and update default.nix, or update it manually with the got: hash from the error message and rebuild.
On a PR, this is covered by PR Risk's required test-nix job (.github/workflows/pr-risk.yml), which runs nix run .#default -- --help plus nix flake check -L (an evaluation of every flake output; the flake has no test checks) on every PR touching go.mod, go.sum, default.nix, flake.nix, or flake.lock -- a superset of plain nix build .#default. .github/workflows/nix-build.yml dropped its own pull_request trigger as redundant (F7c, spec-f7.md §2.4) and now only runs nix build .#default on push to main and on workflow_dispatch, so dependabot bumps that invalidate vendorHash still fail loudly post-merge instead of silently breaking Nix users on main. For dependabot Go-module bumps specifically, .github/workflows/update-vendor-hash.yml runs the same update-nix-vendorhash.sh script and pushes the hash bump back to the dependabot branch automatically (note: GitHub does not retrigger pull_request workflows for GITHUB_TOKEN-authored commits, so a maintainer may need to re-run PR Risk's test-nix once after the auto-fix push to mark the gate green).
Debugging
Use Go's built-in debugging tools:
# Run with verbose logging
go run ./cmd/bd -v create "Test"
# Use delve for debugging
dlv debug ./cmd/bd -- create "Test issue"
Release Process
(For maintainers)
Follow RELEASING.md; it is the canonical release process.
The pre-push version gate requires Go and validates each v* release tag
against the checkout's canonical version. A batch containing different release
versions is refused; push only the tag matching this checkout.
bd preflight finds the nearest Beads source module by walking ancestor
directories, checking both source markers and the module identity. Its version
check runs directly in Go; scripts/check-versions.sh remains a Bash entrypoint.
Questions?
License
By contributing, you agree that your contributions will be licensed under the MIT License.
Code of Conduct
Be respectful and professional in all interactions. We're here to build something great together.
Thank you for contributing to bd! 🎉