From 1cf646529222b54eede537b31e644fb545667406 Mon Sep 17 00:00:00 2001 From: Adrian Bienkowski Date: Tue, 22 Sep 2026 20:44:05 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20document=20issue=20=E2=86=92=20branch?= =?UTF-8?q?=20=E2=86=92=20PR=20workflow=20in=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md described structure, commands and conventions but not how a change is meant to land, so agents had no way to know the repo expects issue → branch → PR. In practice that led to work starting on an already-merged branch, changes with no issue recording the rejected alternatives, and PRs opened without a closing keyword. CONTRIBUTING.md covers some of this for humans but omits the points that are actually got wrong: the branch base, issues, Conventional Commits and the label taxonomy. Documents the six steps with the corresponding gh invocations, including the check that confirms the issue link landed on the PR. --- AGENTS.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index cdabecb..6d7d372 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,6 +46,42 @@ deploy/ — Docker Compose + integration tests - TypeScript: `node:test` framework, `npm run build && node --test dist/*.test.js` - Integration: `make test-integration` (26 test cases via Docker Compose) +## Contribution Workflow + +Every change follows issue → branch → PR. Do not skip the issue: it is where the +problem and the rejected alternatives are recorded, and the PR body is a poor +substitute. + +1. **Open an issue first.** Use the `.github/ISSUE_TEMPLATE/` structure + (`bug_report.md` or `feature_request.md`). State the problem and the concrete + evidence (`file:line`), the proposed solution, and the alternatives considered + *and why they were rejected*. Tick the affected implementations — a change + landing in only one of Go/Rust/TS needs justifying against the equal-peers rule. +2. **Label it.** `Type: *` is required (`Bug`, `Enhancement`, `Feature`, + `Documentation`). Add `Status: Break Change` for anything that alters CLI flags, + config schema, or on-the-wire behaviour. `Priority: P0`–`P3` for bugs. +3. **Branch off `main`**, never off another feature branch. Naming follows the + commit type: `feat/…`, `fix/…`, `docs/…`, `spec/…`. Verify with + `git log origin/main --oneline -1` that you branched from the current head; + merged branches linger locally and are easy to land on by mistake. +4. **Commit with Conventional Commits** (`feat:`, `fix:`, `docs:`, `spec:`, + `chore:`), optionally scoped — `fix(release):`. The release pipeline derives + version bumps from these, so the type is not cosmetic. Mark breaking changes + with `!` (`feat!:`) or a `BREAKING CHANGE:` footer. +5. **Open the PR with a closing keyword** so the issue auto-closes on merge: + `Closes #123` in the body. Fill in `.github/PULL_REQUEST_TEMPLATE.md` honestly — + only tick test boxes for suites actually run, and paste the evidence. +6. **Verify before marking ready.** `make test-all`, `make lint-all`, + `make verify`, and `make test-integration` for anything touching the request + path. Claims of passing tests require pasted output. + +Useful checks: +```sh +gh issue create --title "..." --body-file --label "Type: Enhancement" +gh pr create --base main --title "..." --body-file # body contains "Closes #N" +gh pr view --json closingIssuesReferences # confirm the link landed +``` + ## Repo Standard Reference When implementing code or bootstrapping a new ChainSafe open source repo, follow the [ChainSafe Open Source Repository Standard](docs/repo-standard.md). This defines the required file structure, CI/CD, community files, and release pipeline for all ChainSafe public repos. This repo (`docker-socket-policy`) is the living reference implementation of that standard.