Repository navigation
docs(agents): consolidate build, test, and verification guidance - #2933
Conversation
Promote the universal project guidance that previously lived only in a local CLAUDE.md into the committed agent docs, so every contributor and every tool (Codex/Cursor/etc., not just Claude) gets it from a fresh clone. overview.md gains Build and Development Commands (root + per-package make targets, build env vars), Values schema generation, a Testing section, and Domain references. contributing.md gains a "Verify Before Considering Done" matrix and Review Expectations. Dedup: overview's Git Commits block now points to contributing.md instead of restating it. Assisted-By: Claude <[email protected]> Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request centralizes essential project guidance by migrating information from local configuration files into the official documentation. By consolidating build commands, testing procedures, and contribution standards, the changes ensure that all developers and automated tools have access to up-to-date workflows from a fresh clone. The update also introduces clearer verification steps and review expectations to maintain high code quality across the repository. Highlights
New Features🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on Gemini (@gemini-code-assist) comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (2)
📝 WalkthroughWalkthroughTwo agent documentation files receive new sections: ChangesAgent Documentation and Claude Code Setup
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
dosubot
Bot
added
area/ai
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation in 'docs/agents/contributing.md' and 'docs/agents/overview.md' to include build and development commands, review expectations, and domain-specific task references. The review comments provide actionable suggestions to improve the clarity and precision of the documentation regarding the 'make unit-tests' target and PR description guidelines.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| ```bash | ||
| make build # Build all Docker images (needs: docker, skopeo, jq, gh, helm, yq, GNU tar/sed/awk) | ||
| make unit-tests # Run Helm unit tests across all packages |
There was a problem hiding this comment.
The make unit-tests target in the root Makefile actually runs all unit tests, including Helm unit tests, BATS unit tests, Go unit tests, and other checks. Updating the comment to reflect this will prevent confusion.
| make unit-tests # Run Helm unit tests across all packages | |
| make unit-tests # Run all unit tests (Helm, BATS, Go, etc.) |
There was a problem hiding this comment.
Good catch: make unit-tests aggregates helm-unit-tests bats-unit-tests go-unit-tests rd-presets-check test-check-readiness, so it isn't Helm-only. Updated the comment to "Run all unit tests (Helm, BATS, Go, etc.)" in aaa2688.
|
|
||
| ## Testing | ||
|
|
||
| - **Helm unit tests:** `make unit-tests` (runs `hack/helm-unit-tests.sh` over every package that defines a `test` target). |
There was a problem hiding this comment.
Since make unit-tests runs all unit tests (including Go and BATS), it is more precise to mention make helm-unit-tests for running only the Helm unit tests, or clarify that make unit-tests runs the entire suite.
There was a problem hiding this comment.
Agreed. The Helm-only target is make helm-unit-tests (which invokes hack/helm-unit-tests.sh); make unit-tests runs the full suite. Repointed the bullet at make helm-unit-tests and noted that make unit-tests covers Helm, BATS, Go, and the preset/readiness checks in 71d76ec.
| ## Review Expectations | ||
|
|
||
| - A bug-fix PR should include a behavioural regression test, not just a single field assertion — prove the bug can no longer recur. | ||
| - Keep the PR description on the template: `## What this PR does` plus the `release-note` block. |
There was a problem hiding this comment.
The phrase "Keep the PR description on the template" is slightly awkward. It would be clearer to say "Adhere to the PR description template" or "Keep the PR description matching the template".
There was a problem hiding this comment.
Reworded to "Keep the PR description aligned with the template" in 680e3cc.
github-actions
Bot
added
the
size/M
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/agents/overview.md`:
- Around line 141-148: The documentation link referencing
internal/controller/dashboard/README.md on line 145 is broken because that file
does not exist. You need to either create the missing README.md file at that
path with appropriate documentation about dashboard resources, or update the
reference in the overview.md file to point to an existing file that contains the
relevant dashboard documentation. Check what actually documents the dashboard
resources in your codebase and update the reference accordingly to match an
existing file path.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 2f8aa39a-9650-40ca-ba0e-6c1ac815b153
📒 Files selected for processing (2)
docs/agents/contributing.mddocs/agents/overview.md
Claude Code does not natively support AGENTS.md; add the thin CLAUDE.md shim so all Claude Code sessions pick up the same guidance as other tools. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
Address review feedback from gemini-code-assist on docs/agents/overview.md:72: make unit-tests runs the full suite (Helm, BATS, Go, presets, readiness), not only Helm unit tests. Assisted-By: Claude <[email protected]> Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
Address review feedback from gemini-code-assist on docs/agents/overview.md:103: the Helm-only target is make helm-unit-tests; make unit-tests runs the full unit suite. Point the bullet at the precise target and note the difference. Assisted-By: Claude <[email protected]> Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
Address review feedback from gemini-code-assist on docs/agents/contributing.md:145: reword the awkward "on the template" phrasing to "aligned with the template". Assisted-By: Claude <[email protected]> Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
Address review feedback from coderabbitai on docs/agents/overview.md:145: internal/controller/dashboard/README.md does not exist (no such directory), and there is no dashboard reference doc to point to. Remove the dead bullet; the backups DESIGN.md reference is valid and kept. Assisted-By: Claude <[email protected]> Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
Aleksei Sviridkin (lexfrei)
left a comment
Aleksei Sviridkin (lexfrei)
left a comment
There was a problem hiding this comment.
LGTM — the new build/test/verify content is accurate against the actual Makefile and hack/ tooling, and every bot finding is already addressed. One operational caveat: a documented merge-order dependency on #2932.
Business context: promote universal project guidance that previously lived only in a local (globally-gitignored) CLAUDE.md into the committed agent docs, so every contributor and every tool (via AGENTS.md) gets it from a fresh clone.
Verified the doc claims against source (not just the diff):
REGISTRYdefaultghcr.io/cozystack/cozystack—hack/common-envs.mk:8.PUSH/LOADmap to buildx--push/--load—hack/common-envs.mk:44(BUILDX_ARGS := … --push=$(PUSH) --load=$(LOAD)).make unit-testsaggregates helm/bats/go/rd-presets/readiness —Makefile:101;make helm-unit-testsis the Helm-only target.make generate→hack/update-codegen.sh—Makefile:168.- Per-package
show/apply/diffcome fromhack/package.mk;image/test/generateare defined per package (e.g.image:in 31 package Makefiles). build-depsrequires the documented tool set (docker, skopeo, jq, gh, helm, mikefarah yq, GNU tar/sed/awk) —Makefile:5.
Merge precondition (not a code change)
docs/agents/overview.md:104 links to docs/agents/e2e-testing.md, which exists only on #2932's branch (open, not yet merged). Merging this PR alone ships a dead link — the same class of issue fixed in be716a7e within this very PR. Merge #2932 first, or both together. You already flagged this in the PR body; restating it as a hard gate so it isn't merged standalone by accident.
Non-blocking follow-up
CLAUDE.mdbecomes tracked at the repo root, but.gitignoreignores only.claude/, not the rootCLAUDE.md. Contributors who keep a personal untrackedCLAUDE.md(common for this repo's audience) will hituntracked working tree file 'CLAUDE.md' would be overwrittenon their next pull. Harmless once they move overrides toCLAUDE.local.mdas the wrapper instructs — worth a one-line heads-up in the merge/release note.
2 participants
What this PR does
Promotes universal project guidance that previously lived only in a local
(gitignored)
CLAUDE.mdinto the committed agent docs, so every contributor andevery tool (Codex/Cursor/etc., not just Claude) gets it from a fresh clone.
overview.md: Build & Development Commands (root + per-package make targets,build env vars), Values schema generation, a Testing section, Domain references
contributing.md: a "Verify Before Considering Done" matrix + Review Expectationsoverview.md's Git Commits block now points tocontributing.mdRelease note
Summary by CodeRabbit