Add AGENTS.md documentation for repository development workflow#424
Add AGENTS.md documentation for repository development workflow#424Alanaktion merged 3 commits intomasterfrom
Conversation
Co-authored-by: Alanaktion <236490+Alanaktion@users.noreply.github.com>
Updated repository structure and installation instructions. Removed troubleshooting section for clarity.
There was a problem hiding this comment.
Pull request overview
Adds a new AGENTS.md developer/agent guide intended to document repository structure, tooling, and common workflows for working on Phproject.
Changes:
- Introduces
AGENTS.mdwith setup instructions, repository layout, and development workflow guidance. - Documents code-quality tooling (PHPCS, Rector), testing (PHPUnit), CI matrix, Docker workflows, and plugin conventions.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Security | ||
|
|
||
| Report security vulnerabilities via: | ||
| - [GitHub](https://github.com/Alanaktion/phproject/security/advisories/new) |
There was a problem hiding this comment.
The “Security” reporting instructions conflict with SECURITY.md: the repo asks reporters to use huntr.dev or email, not GitHub Security Advisories. Please align this section with the documented policy to avoid sending reports to the wrong place.
| - [GitHub](https://github.com/Alanaktion/phproject/security/advisories/new) | |
| - [huntr.dev](https://huntr.dev/repos/Alanaktion/phproject/) |
| 2. Implement `_load()` method for initialization | ||
| 3. Implement `_installed()` method to check installation status | ||
| 4. Optionally implement `_install()` method for installation | ||
| 5. Include PHPDoc comment block with `@package` and `@author` tags |
There was a problem hiding this comment.
Plugin requirements are slightly overstated compared to app/plugin/README.md: that doc says the PHPDoc block must contain at least @package and should contain @author, not that @author is mandatory. Please adjust this list to match the source of truth so plugin authors don’t treat optional requirements as required.
| 5. Include PHPDoc comment block with `@package` and `@author` tags | |
| 5. Include a PHPDoc comment block with at least a `@package` tag (an `@author` tag is recommended) |
| vendor/bin/phpunit --no-progress # Run tests without progress output | ||
|
|
||
| # Install application | ||
| php install.php [options] # Interactive or CLI install |
There was a problem hiding this comment.
The quick reference says php install.php [options] is “Interactive or CLI install”, but install.php is interactive in the browser and non-interactive on CLI (it prints help when args are missing). Consider rewording this line to distinguish browser-based install vs. CLI install requiring the --site-* and --admin-* args.
| php install.php [options] # Interactive or CLI install | |
| php install.php --site-* --admin-* [options] # Non-interactive CLI install; requires --site-* and --admin-* arguments | |
| # For interactive install, open the application in a browser and follow the web installer |
| # Code quality checks | ||
| vendor/bin/phpcs # Check code style | ||
| vendor/bin/rector process --dry-run # Check for refactoring suggestions | ||
| find . -name "*.php" ! -path "./vendor/*" -exec php -l {} \; # Syntax check |
There was a problem hiding this comment.
This quick-reference syntax check differs from the earlier “Syntax Check” section and from CI: it omits 2>&1 and any filtering/exit-on-error behavior, so it will print “No syntax errors detected” for every file and still exit 0 even when errors occur in the middle of a pipeline. Please make the quick reference consistent with the recommended/CI command.
| find . -name "*.php" ! -path "./vendor/*" -exec php -l {} \; # Syntax check | |
| if find . -name "*.php" ! -path "./vendor/*" -exec php -l {} \; 2>&1 | grep -v "No syntax errors detected"; then exit 1; fi # Syntax check |
|
|
||
| 1. **Clone the repository:** | ||
| ```bash | ||
| cd /home/runner/work/phproject/phproject |
There was a problem hiding this comment.
The “Clone the repository” step is incorrect/incomplete: it only cds into a GitHub Actions runner path and never performs a git clone. This path won’t exist for most developers, so the setup instructions will fail as written. Update this step to show the actual clone command (and then cd into the repo) using a generic path.
| cd /home/runner/work/phproject/phproject | |
| git clone <repository-url> | |
| cd phproject |
| Basic PHP syntax validation: | ||
|
|
||
| ```bash | ||
| find . -name "*.php" ! -path "./vendor/*" -exec php -l {} 2>&1 \; | grep "syntax error" |
There was a problem hiding this comment.
The suggested syntax-check pipeline will exit with a non-zero status when there are no syntax errors (because grep returns 1 on no matches), which makes it awkward to use in scripts/CI. CI uses an if ... | grep "syntax error, unexpected"; then exit 1; fi pattern to fail only when errors exist—consider mirroring that here (and in the quick reference) for correct exit behavior.
| find . -name "*.php" ! -path "./vendor/*" -exec php -l {} 2>&1 \; | grep "syntax error" | |
| if find . -name "*.php" ! -path "./vendor/*" -exec php -l {} 2>&1 \; | grep "syntax error, unexpected"; then | |
| exit 1 | |
| fi |
Adds comprehensive developer documentation in AGENTS.md covering repository structure, tooling, and workflows for both AI agents and human developers.
Contents
File is structured for rapid scanning with clear headings, code examples, and a command reference section at the end.
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.