You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6514bb2
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: docs/agents/contributing.md
+72-38Lines changed: 72 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,14 +42,14 @@ After every change, verify the relevant artifacts before opening the PR:
42
42
-**Helm templates changed:**`make show` in the package directory renders cleanly.
43
43
-**Go code changed:**`make generate && make manifests` at the repo root, then commit the regenerated files.
44
44
-**`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.
46
46
47
47
## Commit Format
48
48
49
49
Follow [Conventional Commits](https://www.conventionalcommits.org/) with `--signoff`:
@@ -65,12 +65,21 @@ Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREA
65
65
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.
66
66
67
67
**Examples:**
68
+
68
69
```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"
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
+
74
83
### AI Agent Attribution
75
84
76
85
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
**Scope → `area/*`** (full mapping in `.github/workflows/pr-labeler.yaml`):
@@ -148,13 +157,15 @@ If the branch has extra commits, clean it up:
148
157
git fetch upstream
149
158
git checkout -b my-feature upstream/main
150
159
git cherry-pick <your-commit-hash>
151
-
git push -f origin my-feature
160
+
git push --force origin my-feature
152
161
```
153
162
154
163
## Pull Request Body
155
164
156
165
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.
157
166
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
+
158
169
Create the PR with `gh pr create --title "type(scope): brief description" --body-file <file>`.
159
170
160
171
`--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:
### 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
+
168
187
## Downstream Repositories
169
188
170
189
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
290
309
291
310
- A bug-fix PR should include a behavioural regression test, not just a single field assertion — prove the bug can no longer recur.
292
311
- 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).
293
315
294
316
## Fetching Unresolved Review Comments
295
317
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.
297
323
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:
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:
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