docs: add detailed agent instructions for testing and spellchecking #1048
Conversation
There was a problem hiding this comment.
Pull request overview
This PR enhances documentation for AI agents and expands the frontend UI configuration reference. It adds comprehensive testing and spellchecking instructions to AGENTS.md while documenting several previously undocumented UI configuration options.
Key changes:
- Added step-by-step testing and verification workflow to AGENTS.md
- Documented spellcheck configuration and dictionary management for AI agents
- Expanded frontend-ui.md with detailed configuration options for themes, critical path, tag prefixes, trace graphs, and UI controls
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| AGENTS.md | Adds comprehensive testing/verification steps, spellchecking guidance, and documentation versioning instructions for AI agents |
| content/docs/v2/_dev/deployment/frontend-ui.md | Documents new UI configuration options including themes, critical path visualization, top tag prefixes, trace graph settings, and UI control toggles |
| .cspell/project-words.txt | Adds "Emscripten" (GraphViz module technology) to the custom dictionary in correct alphabetical order |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
AGENTS.md
Outdated
| ### Code Quality Checks | ||
|
|
||
| Before creating a PR, run the following checks to ensure CI passes: | ||
|
|
||
| ```bash | ||
| npm run check:format # Check code formatting | ||
| npm run check:spelling # Run spellcheck | ||
| npm run check:links:internal # Check internal links | ||
| npm run check:filenames # Check filename conventions | ||
| ``` | ||
|
|
||
| To automatically fix issues: | ||
|
|
||
| ```bash | ||
| npm run fix:format # Fix formatting issues | ||
| npm run fix:filenames # Fix filename convention violations | ||
| ``` | ||
|
|
There was a problem hiding this comment.
This "Code Quality Checks" section duplicates content already covered in the "Testing and Verifying Changes" section above (lines 79-102). The commands and instructions are identical. Consider removing this duplicate section to avoid redundancy and confusion.
| ### Code Quality Checks | |
| Before creating a PR, run the following checks to ensure CI passes: | |
| ```bash | |
| npm run check:format # Check code formatting | |
| npm run check:spelling # Run spellcheck | |
| npm run check:links:internal # Check internal links | |
| npm run check:filenames # Check filename conventions | |
| ``` | |
| To automatically fix issues: | |
| ```bash | |
| npm run fix:format # Fix formatting issues | |
| npm run fix:filenames # Fix filename convention violations | |
| ``` |
| **For human-centric guidelines** such as DCO (Developer Certificate of Origin) | ||
| signing, PR etiquette, and community interaction, refer to [CONTRIBUTING.md](CONTRIBUTING.md) | ||
| and the [general contributing guidelines](https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md). | ||
|
|
There was a problem hiding this comment.
redundant, everything is already stated above.
There was a problem hiding this comment.
Copilot was not doing what was expected. After putting this here the agent was following instructions.
There was a problem hiding this comment.
Will consolidate it.
| - **Deployment**: Netlify automatically deploys from the `main` branch | ||
| - **Preview**: Netlify creates preview deployments for PRs | ||
|
|
||
| ### Testing and Verifying Changes |
There was a problem hiding this comment.
this looks like a repetition of what was already stated in CONTRIBUTING. There is no point duplicating guidelines (and having them diverge over time).
There was a problem hiding this comment.
Copilot wasn't doing what was requested, so I wanted to be more explicit in the instructions here.
jkowall
force-pushed
the
add-agent-instructions
branch
from
a418233 to
0ce1ee4
Compare
- Add section on testing and verifying changes locally - Add spellchecking guidance with dictionary setup - Add documentation versioning guidelines - Reference human-centric guidelines (DCO, PR etiquette) to CONTRIBUTING.md - Add troubleshooting sections Signed-off-by: Jonah Kowall <[email protected]>
jkowall
force-pushed
the
add-agent-instructions
branch
from
0ce1ee4 to
99d9638
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| directory (e.g., `content/docs/v2/2.x/`) so changes appear immediately on the | ||
| live site |
There was a problem hiding this comment.
The example directory path content/docs/v2/2.x/ is ambiguous and doesn't match the actual directory structure. The most recent version directory would have a specific version number like content/docs/v2/2.13/ (based on the current repository structure). Consider using a more concrete example or clarifying that "2.x" should be replaced with the actual latest version number.
| directory (e.g., `content/docs/v2/2.x/`) so changes appear immediately on the | |
| live site | |
| directory (e.g., `content/docs/v2/2.13/`; replace `2.13` with the latest version | |
| directory) so changes appear immediately on the live site |
2 participants
Summary
This PR enhances the AGENTS.md file with more comprehensive guidance for AI agents working on the documentation.
Changes
Testing and Verification: Added step-by-step instructions for verifying changes locally:
npm installmake developnpm run buildSpellchecking Guidance: Added detailed information about:
.cspell.yml.cspell/directoryproject-words.txt(sorted alphabetically)project-names-src.txtDocumentation Versioning: Added guidance on:
_dev/vs versioned directories)Human-Centric Guidelines Reference: Added note pointing to CONTRIBUTING.md for DCO signing, PR etiquette, and community interaction guidelines.
Troubleshooting: Added section for spellcheck failures.
Testing