Skip to content

Commit 6514bb2

Browse files
committed
docs(agents): define contribution and review requirements
Keep commit history self-contained and issue links visible on the PR. Distinguish commit-reference trailers from issue-closing references. Read review submissions and conversation comments as well as inline threads so outside-diff findings and approvals with feedback are not missed. Require evidence-based replies without dictating phrasing. Validation: Markdown checks and the documented GraphQL query pass. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent b69f2df commit 6514bb2

2 files changed

Lines changed: 73 additions & 38 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313

1414
## What this PR does
1515

16+
<!-- Link the issues this PR addresses. Use Closes #N when it fully resolves an issue; otherwise link it without a closing keyword. -->
1617

1718
### Screenshots
1819

‎docs/agents/contributing.md‎

Lines changed: 72 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -42,14 +42,14 @@ After every change, verify the relevant artifacts before opening the PR:
4242
- **Helm templates changed:** `make show` in the package directory renders cleanly.
4343
- **Go code changed:** `make generate && make manifests` at the repo root, then commit the regenerated files.
4444
- **`values.yaml` annotations changed:** `make generate` in the package; review the `values.schema.json` diff.
45-
- **Migration scripts:** confirm what data actually exists first with `kubectl get <resource> -A -o jsonpath='{...}'` on a dev cluster before writing the logic.
45+
- **Migration scripts:** set `KUBE_CONTEXT` to the human-approved dev-cluster context and confirm the existing data with `kubectl --context "${KUBE_CONTEXT:?}" get <resource> --all-namespaces --output=jsonpath='{...}'` before writing the logic.
4646

4747
## Commit Format
4848

4949
Follow [Conventional Commits](https://www.conventionalcommits.org/) with `--signoff`:
5050

5151
```bash
52-
git commit --signoff -m "type(scope): brief description"
52+
git commit --signoff --message "type(scope): brief description"
5353
```
5454

5555
**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
@@ -65,12 +65,21 @@ Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREA
6565
The subject is imperative and specific; `fix`, `wip` and `update` are not subjects. The body, when there is one, explains why the change is made and only that: the diff already shows what changed and how. Write for a reader who has only `git log`, so no review-iteration or planning vocabulary (`address review comments`, `pass 2`, `batch 1`, `as discussed`) and no bare issue or ticket number in place of the explanation.
6666

6767
**Examples:**
68+
6869
```bash
69-
git commit --signoff -m "feat(dashboard): add config hash annotations to restart pods on config changes"
70-
git commit --signoff -m "fix(postgres): update operator to version 1.2.3"
71-
git commit --signoff -m "docs(contributing): add installation guide"
70+
git commit --signoff --message "feat(dashboard): add config hash annotations to restart pods on config changes"
71+
git commit --signoff --message "fix(postgres): update operator to version 1.2.3"
72+
git commit --signoff --message "docs(contributing): add installation guide"
7273
```
7374

75+
### One Commit, One Logical Change
76+
77+
A commit is the unit a backport cherry-picks and a revert undoes, so it carries exactly one logical change: one fix, one feature, one refactor, together with the regenerated files and tests that belong to it. When the content of a commit changes during review, rewrite that commit (`git commit --amend`, or a `fixup` in `git rebase --interactive`) rather than stacking a correction on top; the branch should read as if each change had been right the first time.
78+
79+
### References to Commits and Issues
80+
81+
A commit that fixes a defect introduced by an earlier commit carries a kernel-style `Fixes:` trailer with at least 12 characters of the hash and the full subject, on one unbroken line, which `git log --max-count=1 --abbrev=12 --format='Fixes: %h ("%s")' <sha>` prints. An issue is referenced as `Closes: #N`, which GitHub also acts on at merge. `Fixes: #N` is not used, so that the `Fixes:` trailer always points at a commit. Reference trailers go after the body and before `Assisted-by:` and `Signed-off-by:`.
82+
7483
### AI Agent Attribution
7584

7685
When an AI agent authors or materially assists with a commit, add exactly one trailer line next to the `Signed-off-by:` trailer that `--signoff` produces:
@@ -102,13 +111,13 @@ Editing the title does not re-run it. The `edited` trigger was dropped in #3211
102111

103112
**Type → `kind/*`:**
104113

105-
| type | label |
106-
| --------- | ------------------ |
107-
| feat | kind/feature |
108-
| fix | kind/bug |
109-
| docs | kind/documentation |
110-
| chore | kind/cleanup |
111-
| refactor | kind/cleanup |
114+
| type | label |
115+
| --- | --- |
116+
| feat | kind/feature |
117+
| fix | kind/bug |
118+
| docs | kind/documentation |
119+
| chore | kind/cleanup |
120+
| refactor | kind/cleanup |
112121
| style, perf, test, build, ci, revert | (no kind label) |
113122

114123
**Scope → `area/*`** (full mapping in `.github/workflows/pr-labeler.yaml`):
@@ -148,13 +157,15 @@ If the branch has extra commits, clean it up:
148157
git fetch upstream
149158
git checkout -b my-feature upstream/main
150159
git cherry-pick <your-commit-hash>
151-
git push -f origin my-feature
160+
git push --force origin my-feature
152161
```
153162

154163
## Pull Request Body
155164

156165
Fill in the template at [`.github/PULL_REQUEST_TEMPLATE.md`](../../.github/PULL_REQUEST_TEMPLATE.md). It includes the required `release-note` block and the [Downstream Repositories](#downstream-repositories) checklist.
157166

167+
Link the issues the PR addresses in its body. Use `Closes #N` when it fully resolves an issue; link partial work without a closing keyword. A closing keyword in a commit can close the issue on merge into the default branch, but does not create the PR's linked-issue entry. Put the reference in the PR body even when the commit already carries it.
168+
158169
Create the PR with `gh pr create --title "type(scope): brief description" --body-file <file>`.
159170

160171
`--body` and `--body-file` replace the body wholesale, so the template is not applied and its checklists are silently dropped. Start the body file from the template instead:
@@ -165,6 +176,14 @@ cp .github/PULL_REQUEST_TEMPLATE.md /tmp/pr-body.md
165176
gh pr create --draft --title "type(scope): brief description" --body-file /tmp/pr-body.md
166177
```
167178

179+
### What Goes in the Commit, What Goes in the PR Body
180+
181+
The commit message is the permanent record: a reader of `git log` or `git blame` years later has it and nothing else. It carries what broke or was missing and for whom, the exact error string verbatim when there is one, so that `git log --grep` finds it, why this design and not the obvious alternative, why it is safe where the diff does not show that, and one line on how it was tested, including the failure path when the change adds one.
182+
183+
The PR body is read once, next to those commits, so it does not repeat them. Its first screen says what is broken or missing, where, and what that costs. After that come one sentence per commit and only what no single commit can carry: results that need the whole series, the environment they came from, decisions the reviewer has to make across commits. Questions to reviewers and open doubts belong in the PR body and never in a commit, where they go stale the day it merges. A fact that fits both goes in the commit.
184+
185+
Size a commit body against accepted commits touching the same files, not against a fixed line cap, which cuts the answers before the narrative. After shortening any of these texts, check that every must-keep fact survived, that every number still sits next to the version or setup it was measured on, that nothing new was added, and that a claim about a set ("every caller", "never happens") is backed by a grep or rewritten as a mechanism.
186+
168187
## Downstream Repositories
169188

170189
Cozystack is upstream for repositories that are **not** kept in sync with it automatically. A change here can break them silently, because nothing in CI compares the two sides.
@@ -290,26 +309,43 @@ The release process keeps a **separate** list of repositories, in [`changelog.md
290309

291310
- A bug-fix PR should include a behavioural regression test, not just a single field assertion — prove the bug can no longer recur.
292311
- Keep the PR description aligned with the template: `## What this PR does` plus the `release-note` block.
312+
- Before posting a claim about a set ("all callers", "the only user", "never happens"), grep for the counterexample, or state the mechanism instead.
313+
- Disagreement carries a mechanism: a code path, a number, a spec clause, a failing test. Time spent and urgency are not arguments.
314+
- Answer the point directly and explain why it is accepted or declined. Read brief feedback literally rather than inferring tone, and avoid unnecessary notifications. Follow the [prose guidance](../../AGENTS.md#working-principles).
293315

294316
## Fetching Unresolved Review Comments
295317

296-
Cozystack uses GitHub review threads with resolution status. Only unresolved threads are actionable — resolved threads are already handled.
318+
Read all three sources before deciding that a review is addressed:
319+
320+
- Unresolved inline threads, including existing replies so an answer is not posted twice.
321+
- Review submission bodies, even when the review also has inline comments or approves the PR. CodeRabbit puts outside-diff findings and some suggestions here.
322+
- General PR conversation comments.
297323

298-
The REST endpoint `/pulls/{pr}/reviews` returns review summaries, not individual review comments. Use the GraphQL API to access `reviewThreads` with `isResolved` status:
324+
Verify each human or automated finding against the current code. Fix valid findings, explain a declined suggestion, and identify follow-up work explicitly. Neither a bot's label nor a human approval replaces that check; an empty inline-thread list does not mean there is no feedback left.
325+
326+
Set `PR_NUMBER` to the PR being handled. This GraphQL query reads the head, review decision, inline threads and review bodies:
299327

300328
```bash
301-
gh api graphql -F owner=cozystack -F repo=cozystack -F pr=<PR_NUMBER> -f query='
329+
gh api graphql --raw-field owner=cozystack --raw-field repo=cozystack \
330+
--field pr="${PR_NUMBER:?}" --raw-field query='
302331
query($owner: String!, $repo: String!, $pr: Int!) {
303332
repository(owner: $owner, name: $repo) {
304333
pullRequest(number: $pr) {
334+
headRefOid
335+
reviewDecision
305336
reviewThreads(first: 100) {
337+
pageInfo { hasNextPage endCursor }
306338
nodes {
339+
id
307340
isResolved
341+
isOutdated
308342
comments(first: 100) {
343+
pageInfo { hasNextPage endCursor }
309344
nodes {
310345
id
311346
path
312347
line
348+
originalLine
313349
author { login }
314350
bodyText
315351
url
@@ -318,32 +354,30 @@ query($owner: String!, $repo: String!, $pr: Int!) {
318354
}
319355
}
320356
}
357+
reviews(first: 100) {
358+
pageInfo { hasNextPage endCursor }
359+
nodes {
360+
id
361+
state
362+
body
363+
author { login }
364+
submittedAt
365+
url
366+
commit { oid }
367+
}
368+
}
321369
}
322370
}
323-
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[]'
371+
}' --jq '.data.repository.pullRequest'
324372
```
325373

326-
Compact one-line variant:
374+
For every connection reporting `hasNextPage: true`, fetch the remaining pages with its `endCursor`, including comments within a thread. Filter resolved threads only after collection; do not discard a review body because its review also has inline comments.
375+
376+
Fetch the PR conversation separately through the issue-comments endpoint:
327377

328378
```bash
329-
gh api graphql -F owner=cozystack -F repo=cozystack -F pr=<PR_NUMBER> -f query='
330-
query($owner: String!, $repo: String!, $pr: Int!) {
331-
repository(owner: $owner, name: $repo) {
332-
pullRequest(number: $pr) {
333-
reviewThreads(first: 100) {
334-
nodes {
335-
isResolved
336-
comments(first: 100) {
337-
nodes {
338-
path
339-
line
340-
author { login }
341-
bodyText
342-
}
343-
}
344-
}
345-
}
346-
}
347-
}
348-
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[] | "\(.path):\(.line // "N/A") - \(.author.login): \(.bodyText[:150])"'
379+
gh api "repos/cozystack/cozystack/issues/${PR_NUMBER:?}/comments?per_page=100" \
380+
--paginate --jq '.[] | {author: .user.login, body, url: .html_url}'
349381
```
382+
383+
If `reviewDecision` still reports `CHANGES_REQUESTED` but no remaining point explains it, recheck the review bodies, replies and pagination before declaring the review complete.

0 commit comments

Comments
 (0)