Skip to content

Commit 7475c5a

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, 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]>
1 parent 1e7ba63 commit 7475c5a

2 files changed

Lines changed: 47 additions & 66 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. 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. -->
1617

1718
### Screenshots
1819

‎docs/agents/contributing.md‎

Lines changed: 46 additions & 66 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:** 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.
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`, `security`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
@@ -67,12 +67,23 @@ Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREA
6767
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.
6868

6969
**Examples:**
70+
7071
```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"
73-
git commit --signoff -m "docs(contributing): add installation guide"
72+
git commit --signoff --message "feat(dashboard): add config hash annotations to restart pods on config changes"
73+
git commit --signoff --message "fix(postgres): update operator to version 1.2.3"
74+
git commit --signoff --message "docs(contributing): add installation guide"
7475
```
7576

77+
### One Commit, One Logical Change
78+
79+
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+
7687
### AI Agent Attribution
7788

7889
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
104115

105116
**Type → `kind/*`:**
106117

107-
| type | label |
108-
| --------- | ------------------ |
109-
| feat | kind/feature |
110-
| fix | kind/bug |
111-
| docs | kind/documentation |
112-
| chore | kind/cleanup |
113-
| refactor | kind/cleanup |
118+
| type | label |
119+
| --- | --- |
120+
| feat | kind/feature |
121+
| fix | kind/bug |
122+
| docs | kind/documentation |
123+
| chore | kind/cleanup |
124+
| refactor | kind/cleanup |
114125
| security, style, perf, test, build, ci, revert | (no kind label) |
115126

116127
**Scope → `area/*`** (full mapping in `.github/workflows/pr-labeler.yaml`):
@@ -150,13 +161,17 @@ If the branch has extra commits, clean it up:
150161
git fetch upstream
151162
git checkout -b my-feature upstream/main
152163
git cherry-pick <your-commit-hash>
153-
git push -f origin my-feature
164+
git push --force origin my-feature
154165
```
155166

156167
## Pull Request Body
157168

158169
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.
159170

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+
160175
Create the PR with `gh pr create --title "type(scope): brief description" --body-file <file>`.
161176

162177
`--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:
@@ -167,6 +182,14 @@ cp .github/PULL_REQUEST_TEMPLATE.md /tmp/pr-body.md
167182
gh pr create --draft --title "type(scope): brief description" --body-file /tmp/pr-body.md
168183
```
169184

185+
### 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+
170193
## Downstream Repositories
171194

172195
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
292315

293316
- A bug-fix PR should include a behavioural regression test, not just a single field assertion — prove the bug can no longer recur.
294317
- 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).
295321

296-
## Fetching Unresolved Review Comments
322+
## Collecting Review Feedback
297323

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:
299325

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.
328+
- General PR conversation comments.
329+
- Comments posted directly on the PR's commits.
301330

302-
```bash
303-
gh api graphql -F owner=cozystack -F repo=cozystack -F pr=<PR_NUMBER> -f query='
304-
query($owner: String!, $repo: String!, $pr: Int!) {
305-
repository(owner: $owner, name: $repo) {
306-
pullRequest(number: $pr) {
307-
reviewThreads(first: 100) {
308-
nodes {
309-
isResolved
310-
comments(first: 100) {
311-
nodes {
312-
id
313-
path
314-
line
315-
author { login }
316-
bodyText
317-
url
318-
createdAt
319-
}
320-
}
321-
}
322-
}
323-
}
324-
}
325-
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[]'
326-
```
327-
328-
Compact one-line variant:
329-
330-
```bash
331-
gh api graphql -F owner=cozystack -F repo=cozystack -F pr=<PR_NUMBER> -f query='
332-
query($owner: String!, $repo: String!, $pr: Int!) {
333-
repository(owner: $owner, name: $repo) {
334-
pullRequest(number: $pr) {
335-
reviewThreads(first: 100) {
336-
nodes {
337-
isResolved
338-
comments(first: 100) {
339-
nodes {
340-
path
341-
line
342-
author { login }
343-
bodyText
344-
}
345-
}
346-
}
347-
}
348-
}
349-
}
350-
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | .comments.nodes[] | "\(.path):\(.line // "N/A") - \(.author.login): \(.bodyText[:150])"'
351-
```
331+
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

Comments
 (0)