Skip to content
Metrics Book
Not released yet: version 0.1 is being built. See what works today.

Contributing

People and agents follow the same rules. The full guide is CONTRIBUTING.md in the repository, and AGENTS.md holds the same rules in the form an agent reads.

Agree first

Section titled “Agree first”

Anything bigger than a small fix starts as an issue, so the change is agreed before it is built. A typo, a broken link or a bug fix with its test can go straight to a pull request.

Set up

Section titled “Set up”

You need uv, Node 24 with pnpm 11, and Docker. From the repository root:

Terminal window
uv sync
pnpm install
mb dev up

uv sync installs mb and the job runner from your checkout. mb dev up builds the images and runs the whole stack on examples/ecommerce/ with sample data. Several checkouts can run side by side: ports and names come from a hash of the checkout’s path.

Check the change

Section titled “Check the change”
Terminal window
mb fmt          # every formatter
mb check        # format, lint, types and tests of the areas you changed
mb check --all  # everything, with the security scanners

Run the smallest check that catches your change while you work, and mb check --all --e2e before you open a pull request. Tests run against real Postgres, never a mock, and a skipped test counts as a failed one.

Open a pull request

Section titled “Open a pull request”
  • One branch per task. Write each commit subject as an instruction: “Exclude test orders from net sales”.
  • Use the pull request template. It asks what changed in business words, which layers it touches, which checks you ran and how long they took.
  • A person reviews every pull request. Agents propose; people merge.
  • If an agent wrote the change, the person who opens the pull request has read the diff and answers for it.

Security

Section titled “Security”

Never read, print or commit a secret value. Never delete, skip or loosen a security test to make a change pass. Report a vulnerability privately through GitHub security advisories, not in an issue.

Licence

Section titled “Licence”

Metrics Book is Apache-2.0. Under section 5 of the licence, your contribution is offered under the same terms. Everyone taking part follows the Code of Conduct.