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>
415 lines
18 KiB
Markdown
415 lines
18 KiB
Markdown
# 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](ROADMAP.md); work in a priority
|
||
area is reviewed first.
|
||
|
||
## Development Setup
|
||
|
||
### Prerequisites
|
||
|
||
- [Bazelisk](https://github.com/bazelbuild/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.mod` for the required version; currently 1.26+), for `make
|
||
install` and the `go test` inner 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](engdocs/ICU-POLICY.md)
|
||
|
||
### Getting Started
|
||
|
||
```bash
|
||
# 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](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 your `user.bazelrc` or
|
||
`.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](engdocs/TESTING.md) 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](https://golang.org/doc/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.
|
||
|
||
```bash
|
||
# 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](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](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](#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](https://www.conventionalcommits.org/):
|
||
`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](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](https://steve-yegge.medium.com/zero-framework-cognition-a-way-to-build-resilient-ai-applications-56b090ed3e69). 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](engdocs/TESTING.md).
|
||
|
||
### Before Opening a PR
|
||
|
||
- Follow the proportional validation budget in
|
||
[engdocs/TESTING.md](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-skip` and file an issue if it's not already tracked
|
||
(see [engdocs/TESTING.md](engdocs/TESTING.md#failures-skips-and-review)).
|
||
- 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](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](https://github.com/gastownhall/beads/issues/new?template=bug_report.yml)
|
||
or [feature request](https://github.com/gastownhall/beads/issues/new?template=feature_request.yml).
|
||
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](https://github.com/gastownhall/beads/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](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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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](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](https://github.com/gastownhall/beads/issues)
|
||
- Open a new issue for questions
|
||
- Review [README.md](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! 🎉
|