beads/CONTRIBUTING.md
Julian Knutsen 298e38aea4 docs(contributing): recommend issues when they add context instead of requiring one per PR
#7223 made a linked, documented issue mandatory for every PR. That is
the right default for user-visible bugs and changes worth discussing,
but it adds ceremony to small, self-explanatory fixes without adding
context.

AGENTS.md, CONTRIBUTING.md, ROADMAP.md, the PR template and the feature
form now advise filing an issue when it adds context and let small fixes
go straight to a PR whose description explains the why. End-to-end
evidence is still required, and Closes #N is used when an issue exists.
No CI check or ruleset enforced the requirement; scripts/pr-preflight.sh
already only warns when a PR has no closing issue.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 23:21:31 +00:00

17 KiB
Raw Permalink Blame History

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.mod for the required version; currently 1.26+)
  • Git
  • A C compiler (CGO is required for the embedded Dolt database)
  • golangci-lint v2.10.1 for the required local lint gate
  • 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
└── .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 gofmt to 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

Use the same pinned golangci-lint version and repository-owned wrapper as CI:

# Install the version pinned by CI
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1

# Run the required formatting and lint contract
make ci-pr-lint

make ci-pr-lint must pass with zero issues. It checks formatting, lints the repository's normal gms_pure_go build, and cross-lints Windows-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 required wrapper on all pull requests.

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

  1. If the change warrants one, find or file an issue (see Issues and pull requests)
  2. Fork the repository and create a feature branch (git checkout -b feature/my-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Run tests and linter locally
  6. Commit your changes with clear messages
  7. Push to your fork
  8. 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 What and Why so reviewers can grasp the goal without reading the diff. .github/PULL_REQUEST_TEMPLATE.md is 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-skip and 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  1. Automated checks (tests, linting) must pass
  2. At least one maintainer approval required
  3. Address review feedback
  4. 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?

  • Check existing issues
  • Open a new issue for questions
  • Review README.md and other documentation

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! 🎉