Add Agent Playbook section for automated updates - #347
Conversation
Up to standards ✅🟢 Issues
|
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a comprehensive Agent Playbook to the documentation, which is currently up to Codacy standards. It effectively outlines the engine architecture, version management across different build systems (sbt, composer), and the update lifecycle.
A significant process issue was identified in the 'Step-by-step update procedure'. The instructions advise reviewers or agents to diff generated files (such as patterns.json) to verify changes; however, because these files are gitignored, a standard environment will not have a baseline for comparison. This logic gap should be addressed by adding a baseline generation step to ensure the update impact is actually reviewable.
Test suggestions
- Verify documentation provides specific commands for regenerating composer.lock
- Verify documentation specifies the sbt command for the doc-generator subproject
- Verify documentation identifies which files are gitignored (e.g., generated documentation files)
- Verify documentation provides a troubleshooting table for common failures like dependency resolution or pattern drift
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
|
|
||
| 1. **Bump the version(s)** in `composer.json`'s `require` block (and `.circleci/config.yml` orbs / `Dockerfile` base images / `build.sbt`, if applicable) as scoped by the task. | ||
| 2. **Regenerate `composer.lock`** to match: `composer update <package/name> --with-dependencies` (requires PHP + Composer locally, or run inside the `php:8.5-cli` stage). Commit the updated lock file alongside `composer.json`. | ||
| 3. **Regenerate the docs.** Requires `phpdoc` on `PATH` (see the `wget`/`phpDocumentor.phar` block at the top of the existing "Generating the documentation" section above), plus network access for the parsers to reach upstream plugin repositories: `sbt "doc-generator/runMain codacy.codesniffer.docsgen.GeneratorMain"`. This produces (locally, not committed) `docs/patterns.json`, `docs/description/description.json`, and the per-pattern `docs/description/*.md` files. Review the diff for new/removed/renamed patterns. |
There was a problem hiding this comment.
🟡 MEDIUM RISK
Suggestion: The instructions ask to 'Review the diff for new/removed/renamed patterns,' but since the generated documentation files are gitignored (as noted on lines 126 and 151), a standard git diff will not show any changes. To make this reviewable, the playbook should include a step to generate the documentation before applying version bumps to create a local baseline. This ensures that when the documentation is regenerated after the version bump, the agent can perform a local diff (e.g., using diff or git diff --no-index) to verify pattern changes.
1 participant
Summary
Test plan