Skip to content

Commit 7e887ed

Browse files
authored
docs(agents): document make generate requirement before committing (#2469)
## What this PR does Adds explicit guidance to `docs/agents/contributing.md` about running `make generate` in any touched package before committing. Pre-commit CI runs `make generate` in every package and fails with exit code 123 on any uncommitted generator output (regenerated `README.md`, reordered `values.schema.json`, refreshed `packages/system/<name>-rd/cozyrds/<name>.yaml`). Recent PRs have tripped on this during review cycles. Documenting it in the contributing checklist saves a round-trip. ### Release note ```release-note NONE ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Require regenerating and committing generated artifacts when designated source files are edited. * Added a section listing generated artifacts per package and concrete regeneration/staging steps. * Documented CI enforcement that detects unstaged generator output and blocks PRs. * Added guidance for rerunning generation after amended commits, plus updated commit-scope guidance (now “not exhaustive”) and included “agents” in allowed scopes. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 24d48bd + 4813566 commit 7e887ed

1 file changed

Lines changed: 26 additions & 2 deletions

File tree

‎docs/agents/contributing.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,30 @@ Project-side conventions for commits, branches, and pull requests in Cozystack.
88
- [ ] Commit is signed off with `--signoff`
99
- [ ] Branch is rebased on `upstream/main` (no extra commits)
1010
- [ ] PR body includes description and release note
11+
- [ ] Ran `make generate` in every package whose `values.yaml`, `values.schema.json`, `Chart.yaml`, or `README.md` was touched, and committed the regenerated files
12+
13+
## Regenerate Artifacts Before Committing
14+
15+
Several files in each package are produced by `make generate` from `values.yaml` + `values.schema.json` and must stay in sync with the hand-edited sources:
16+
17+
- `packages/(apps|extra)/<name>/README.md` — regenerated by `cozyvalues-gen` (parameter table, formatting).
18+
- `packages/(apps|extra)/<name>/values.schema.json` — `cozyvalues-gen` rewrites ordering and derived fields.
19+
- `packages/system/<name>-rd/cozyrds/<name>.yaml` — produced by `hack/update-crd.sh`, which `make generate` invokes.
20+
21+
**Before committing edits to any of those sources**, run `make generate` inside the package and stage the full diff:
22+
23+
```bash
24+
make -C packages/<apps-or-extra>/<name> generate
25+
git add packages/<apps-or-extra>/<name>/ packages/system/<name>-rd/
26+
```
27+
28+
The repo's pre-commit CI job runs `make generate` in every package and then `git diff --exit-code`. Any unstaged generator output fails the job with exit code 123 and blocks the PR. Also rerun `make generate` after a `git commit --amend` if the amended change touched any of the sources above.
29+
30+
To locate packages a WIP branch likely needs to be regenerated:
31+
32+
```bash
33+
git diff --name-only | xargs -n1 dirname | sort -u | grep ^packages/
34+
```
1135

1236
## Commit Format
1337

@@ -19,10 +43,10 @@ git commit --signoff -m "type(scope): brief description"
1943

2044
**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
2145

22-
**Scopes:**
46+
**Scopes** (e.g., not exhaustive — use any scope that names the component you are touching):
2347
- System: `dashboard`, `platform`, `cilium`, `kube-ovn`, `linstor`, `fluxcd`, `cluster-api`
2448
- Apps: `postgres`, `mariadb`, `redis`, `kafka`, `clickhouse`, `virtual-machine`, `kubernetes`
25-
- Other: `api`, `hack`, `tests`, `ci`, `docs`, `maintenance`
49+
- Other: `api`, `hack`, `tests`, `ci`, `docs`, `agents`, `maintenance`
2650

2751
Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREAKING CHANGE:` footer.
2852

0 commit comments

Comments
 (0)