* ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) Lint and vet now run as nogo inside the Bazel build, so they gate wherever the Bazel lanes execute (rbe-west), and the golangci-lint and go vet jobs leave pr.yml and main.yml. - //tools/nogo (own go.mod, joined to beads' for go_deps only through gazelle.go.work): go test's vet checks (cmd/go's defaultVetFlags, the set scripts/ci/go-test-vet.sh ran) plus the eight linters .golangci.yml enables, each a wrapper over the library version golangci-lint v2.10.1 uses (depguard, errcheck, forbidigo, gosec, misspell, sloglint, unconvert, unparam). - .golangci.yml stays the single lint policy: Bazel embeds it and tools/nogo/internal/golangci applies it as golangci-lint does (enabled set, settings, run.tests: false as library-unit-only analysis, lax generated-file detection, path/path-except/text exclusion rules), with strict decoding so an unimplemented key fails the build. - gascity's rules_go //nolint-range patch and x/tools ctrlflow patch, byte-identical. - Windows/darwin: cross-configured, not a golangci leg. The pure lane's release cross-compile (//tools/bazel:release_cross, every library and binary for all eight release platforms, cgo off) runs nogo on every compile, a superset of golangci-lint's windows and darwin legs. scripts/pr-lint (make ci-pr-lint, bd preflight) runs `bazel build --config=nogo //...` plus release_cross for windows_amd64,darwin_arm64. release_cross skips tools/nogo, a separate Go module `go build ./...` never compiled. - pr.yml: scripts-go-checks (vet) and pr-lint-wrapper (x3) are gone, with their ci-gate entries; main.yml: pr-lint-wrapper (x6) and go-vet-cache. scripts/ci/go-test-vet.sh and install-golangci-lint.sh are deleted. - pre-commit hook and .pre-commit-config.yaml run `make lint-changed LINT_CHANGED_SCOPE=staged` (nogo over the staged packages); Makefile adds lint, vet and lint-changed. pr-lint.sh no longer runs gofmt (//scripts/repochecks:fmt_test owns it; ga-96smfk.41). - internal/testutil/integration: five gosec findings in integration-tagged library files golangci-lint never built, now linted by the integration lanes, carry reasoned //nolint directives. Parity: with the exclusion rules removed, golangci-lint and nogo report the same 3,916 findings natively and 3,859 each for windows and darwin (file, line, linter, text); with .golangci.yml as committed both report none. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * ci(bazel): equivalence.py leaves nested Go modules' tests out of go test's set tools/nogo is its own Go module, so `go test ./...` in the root never runs its tests; Bazel's unit lane does. Its packages are neither expected nor extra. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
17 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
- Go (see
go.modfor the required version; currently 1.26+) - Git
- A C compiler (CGO is required for the embedded Dolt database)
- Bazelisk (installed as
bazel) for the required lint and vet gate (make ci-pr-lint) and the pre-commit hook - 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
# Build the project (uses gms_pure_go tag via Makefile)
make build
# Run tests (uses correct build tags automatically)
make test
# Build and install locally to ~/.local/bin
make install
Optional: if you use Bazel, opt in to the project's anonymous, read-only
build cache by adding build --config=fork-cache to your gitignored
.bazelrc.local (or pass --config=fork-cache per command). Results CI
already computed become cache hits, and nothing you build is uploaded. It is
off by default.
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. - 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 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! 🎉