docs: add agents documentation and CI validation instructions#696
docs: add agents documentation and CI validation instructions#696ilopezluna merged 2 commits intomainfrom
Conversation
Summary of ChangesHello @ilopezluna, 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 significantly enhances the developer experience for contributors by providing a unified local validation command ( Highlights
🧠 New Feature in Public Preview: You can now enable Memory 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. Changelog
Activity
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 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 counter productive. You can react with 👍 and 👎 on @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. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- In
AGENTS.md, the prerequisiteGo 1.25.6+appears to reference a non-existent Go version; consider correcting this to the actual minimum supported Go version (e.g., 1.22.x) to avoid confusing contributors.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `AGENTS.md`, the prerequisite `Go 1.25.6+` appears to reference a non-existent Go version; consider correcting this to the actual minimum supported Go version (e.g., 1.22.x) to avoid confusing contributors.
## Individual Comments
### Comment 1
<location> `AGENTS.md:22` </location>
<code_context>
+
+### Prerequisites
+
+- **Go 1.25.6+**
+- **golangci-lint v2.7.2+** — [Install instructions](https://golangci-lint.run/welcome/install/)
+- **shellcheck** — `brew install shellcheck` (macOS) or `apt-get install shellcheck` (Linux)
</code_context>
<issue_to_address>
**issue (typo):** The documented Go version `1.25.6+` looks incorrect and may be a typo for a currently available Go release.
Prerequisites list `Go 1.25.6+`, but there is no 1.25.x Go release. Please confirm the intended minimum Go version (e.g., `1.22.6+`) and update this entry so contributors know which version to install.
```suggestion
- **Go 1.22.6+**
```
</issue_to_address>
### Comment 2
<location> `AGENTS.md:16` </location>
<code_context>
+1. **go mod tidy** — ensures `go.mod`/`go.sum` are clean
+2. **Lint** — runs `golangci-lint` (see [`.golangci.yml`](./.golangci.yml) for configuration)
+3. **Tests** — runs all unit tests with race detection (`go test -race ./...`)
+4. **Shellcheck** — validates all shell scripts
+
+If any step fails, fix the issue and re-run before committing.
</code_context>
<issue_to_address>
**nitpick (typo):** Consider using the official capitalization "ShellCheck" for the tool name and keeping it consistent.
Here it’s written as "Shellcheck" and elsewhere as `shellcheck`. Please standardize on the official tool name "ShellCheck" when referring to it in text, and use lowercase `shellcheck` only for the command/package name.
Suggested implementation:
```
4. **ShellCheck** — validates all shell scripts
```
```
- **ShellCheck** — `brew install shellcheck` (macOS) or `apt-get install shellcheck` (Linux)
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![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 introduces a valuable validate-all Makefile target and an AGENTS.md guide, which significantly improves the local development workflow and CI parity for contributors. The additions are well-integrated into the existing documentation and help system. I have identified a likely typo in the linter version and a small opportunity to clarify an error message.
Makefile
Outdated
| validate-all: | ||
| @echo "==> Checking go mod tidy..." | ||
| @go mod tidy | ||
| @git diff --exit-code go.mod go.sum || (echo "ERROR: go.mod/go.sum are not tidy. Run 'go mod tidy' and commit the changes." && exit 1) |
There was a problem hiding this comment.
The error message currently instructs the user to run go mod tidy, but the validate-all target has already executed that command on the previous line. It would be more helpful to inform the user that the files were modified and they should commit the changes.
@git diff --exit-code go.mod go.sum || (echo "ERROR: go.mod/go.sum were not tidy. Please commit the changes applied by 'go mod tidy'." && exit 1)
2 participants
External contributors can't run CI workflows on their forks, so they submit PRs that fail CI silently. Maintainers only discover failures after manually triggering workflows, creating a slow feedback loop.
Added
make validate-all— a single command that runs all CI checks locally (go mod tidy, lint, tests with race detection, shellcheck). CreatedAGENTS.mdinstructing contributors/agents to run it before committing, with prerequisites and links to project docs. Updated README.md to reflect all current Makefile targets.