Builder Garage
← Learn

Your first contribution

View source ↗

Your First Contribution

Builder Garage-specific. This guide walks a first-time contributor through one change to Builder Garage, from finding an issue to an open pull request. It adds no requirement. CONTRIBUTING.md, GOVERNANCE.md, and the canonical skills govern, and each step below links to the source that defines it. Where this guide and a source differ, the source governs.

1. Find an issue and ask to work on it

Look for open issues labelled good first issue, which are good for newcomers, or help wanted, where extra attention is needed.

Ask to work on the issue in a comment on it, and wait for a maintainer to assign it. Assignment coordinates work. It does not approve the change. See Working on an existing issue.

Read the issue's acceptance criteria and scope before starting. The issue is the durable record of the change (Start from an issue).

2. Set up

  • Build and validate. Build from source lists the Go version, and Develop and validate lists the checks, including make check.
  • Install garage. The skills resolve this project's configuration through garage config validate, so your agent needs a garage binary on its PATH. Install from source puts one there. Check the platforms it supports in Current limitations.
  • Install the skills. If you work with an agent, install the canonical skills for it as Skill installation describes.

3. Follow the path from issue to merge

A change goes from issue to implementation, independent review, any correction and re-review, commit and pull request, and maintainer approval and merge. How a substantive change proceeds defines each step, and the gate map shows the gates in order.

Two gates are separate: independent engineering review before the change is proposed as a pull request, and maintainer approval of the pull request before merge. Neither replaces the other (Two separate gates).

4. Implement and review in separate execution contexts

You hold the separation between implementation and independent review yourself. Run the implementation and the independent review as separate invocations, in separate execution contexts, in your own workspace, and post both records on the originating issue. This is the path the #98 D1 decision set for external contributors, and Obtain independent review states it.

The procedures are application-implementation-workflow for implementation and independent-implementation-review for the review. README's Skill shorthand lists their short names. No particular AI model, vendor, or tool is required.

5. Post the two records on the issue

Two records go on the originating issue:

  1. The implementation record, [AGENT #1 — IMPLEMENTATION], posted when the change is ready for review. By default the change is still uncommitted. Under commit-stage review, it is pushed to a branch with no pull request. See Agent #1 completion record.
  2. The review record, [AGENT #2 — INDEPENDENT REVIEW], posted by the separate review context. See Agent #2 review record.

Each carries a garage-evidence block that identifies the exact change with its garage-artifact-v1 identity. Compute it with the reference procedure. Where each record lives lists every record, including the one that goes on the pull request.

6. Know what garage status shows

garage status <issue> reads the issue's records from GitHub. It counts a workflow record only when its author is an owner, member, or collaborator of the repository, and reports the others as ignored (Workflow status, #40 decision). If you are not a collaborator, your records appear as ignored there. They are still the durable record on the issue.

7. Open the pull request

After the review record approves the change, commit exactly the approved change, push it to a branch in your fork, and open a pull request against main. If the change was already pushed for commit-stage review, open the pull request from that reviewed commit instead (Commit, push, and open a pull request).

A maintainer then reviews and approves the pull request, and it merges after all required checks pass (Maintainer approval and merge). Independent review approval does not authorize merge.