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 7475c5a
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,
and reserve closing keywords for complete fixes.
Include review bodies, conversation and commit comments alongside inline
threads without imposing the same review depth on every change. Verify
feedback against current code before acting on it.
Validation: markdownlint passes with MD013 excluded, and MD041 excluded
for the PR template, whose existing first heading is level two.
Assisted-by: LLM
Signed-off-by: Aleksei Sviridkin <[email protected]>
Copy file name to clipboardExpand all lines: .github/PULL_REQUEST_TEMPLATE.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,7 @@
13
13
14
14
## What this PR does
15
15
16
+
<!-- Link the issues this PR addresses. For a complete fix targeting the default branch, use Closes #N (Closes owner/repository#N for another repository). Otherwise use a non-closing reference; release-branch PRs need manual issue linking and closure when appropriate. -->
Copy file name to clipboardExpand all lines: docs/agents/contributing.md
+46-66Lines changed: 46 additions & 66 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:**when the task supplies a kubeconfig, export its path as `KUBECONFIG`. 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`:
@@ -67,12 +67,23 @@ Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREA
67
67
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.
68
68
69
69
**Examples:**
70
+
70
71
```bash
71
-
git commit --signoff -m"feat(dashboard): add config hash annotations to restart pods on config changes"
72
-
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. If another commit in the series names the rewritten commit in a `Fixes:` trailer, update that reference to its new hash and subject.
80
+
81
+
### References to Commits and Issues
82
+
83
+
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. `Fixes: #N` is not used, so that the `Fixes:` trailer always points at a commit.
84
+
85
+
Use `Closes: #N` only when the change fully resolves the issue. For partial work, use a non-closing reference such as `Refs: #N`; a closing commit trailer can close the issue when it reaches the default branch even if the PR body uses a non-closing link. For an issue in another repository, qualify the reference as `owner/repository#N`, including in a closing trailer (`Closes: owner/repository#N`). Reference trailers go after the body and before `Assisted-by:` and `Signed-off-by:`.
86
+
76
87
### AI Agent Attribution
77
88
78
89
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:
@@ -104,13 +115,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`):
@@ -150,13 +161,17 @@ If the branch has extra commits, clean it up:
150
161
git fetch upstream
151
162
git checkout -b my-feature upstream/main
152
163
git cherry-pick <your-commit-hash>
153
-
git push -f origin my-feature
164
+
git push --force origin my-feature
154
165
```
155
166
156
167
## Pull Request Body
157
168
158
169
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.
159
170
171
+
Link the issues the PR addresses in its body. Use `Closes #N` when it fully resolves an issue, or `Closes owner/repository#N` for another repository; 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.
172
+
173
+
GitHub interprets closing keywords in a PR description only when it targets the default branch. For a release-branch PR, use a non-closing reference and have a maintainer with write access link the issue manually and close it separately when appropriate. See [GitHub's issue-linking rules](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
174
+
160
175
Create the PR with `gh pr create --title "type(scope): brief description" --body-file <file>`.
161
176
162
177
`--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
186
+
187
+
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.
188
+
189
+
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.
190
+
191
+
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.
192
+
170
193
## Downstream Repositories
171
194
172
195
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.
@@ -292,60 +315,17 @@ The release process keeps a **separate** list of repositories, in [`changelog.md
292
315
293
316
- A bug-fix PR should include a behavioural regression test, not just a single field assertion — prove the bug can no longer recur.
294
317
- Keep the PR description aligned with the template: `## What this PR does` plus the `release-note` block.
318
+
- Before posting a claim about a set ("all callers", "the only user", "never happens"), grep for the counterexample, or state the mechanism instead.
319
+
- Disagreement carries a mechanism: a code path, a number, a spec clause, a failing test. Time spent and urgency are not arguments.
320
+
- 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).
295
321
296
-
## Fetching Unresolved Review Comments
322
+
## Collecting Review Feedback
297
323
298
-
Cozystack uses GitHub review threads with resolution status. Only unresolved threads are actionable — resolved threads are already handled.
324
+
Read the feedback from these sources, including existing replies:
299
325
300
-
The REST endpoint `/pulls/{pr}/reviews` returns review summaries, not individual review comments. Use the GraphQL API to access `reviewThreads` with `isResolved` status:
326
+
- Unresolved inline review threads.
327
+
- Review submission bodies, even when the review also has inline comments.
Verify each human or automated finding against the current code before deciding whether it needs a change. Do not post a duplicate answer to a point already addressed.
0 commit comments