From 207edca8969d85739f22cec1b41385e31764646b Mon Sep 17 00:00:00 2001 From: Jacek Pyziak Date: Sun, 22 Feb 2026 11:45:55 +0100 Subject: [PATCH] feat: Add repository guidelines for project structure, development commands, coding style, and testing --- AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7eab89f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# Repository Guidelines + +## Project Structure & Module Organization +BackPRO is a custom PHP MVC application (no Laravel/Symfony). Main code lives in `src/` under PSR-4 namespace `App\\`. +- `src/Core/`: bootstrap, routing, base controller/model, config/auth helpers. +- `src/Controllers/`, `src/Models/`, `src/Services/`: HTTP actions, data access, external integrations. +- `templates/`: PHP view templates. +- `config/routes.php`: all route definitions. +- `cron/`: CLI jobs (`publish.php`, `semstorm.php`). +- `migrations/`: ordered SQL schema changes (`001_*.sql`, `002_*.sql`, ...). +- `assets/`: CSS/JS and WordPress theme files. +- `storage/logs/`: runtime logs. + +## Build, Test, and Development Commands +- `composer install`: install PHP dependencies. +- `php -S localhost:8000 -t .`: run local dev server from repository root. +- `php cron/publish.php`: run publishing workflow manually. +- `php cron/semstorm.php`: sync SEO metrics manually. +- `php -l src\\Services\\PublisherService.php`: lint a PHP file (repeat per changed file). + +## Coding Style & Naming Conventions +- Target PHP `>=8.1` (see `composer.json`), use strict typing where applicable. +- Follow PSR-4 and existing suffix patterns: `*Controller`, `*Service`, `*Model`. +- Use 4-space indentation and braces/newline style consistent with `src/Core/App.php`. +- Keep controllers thin; move API/business logic to `src/Services/`. +- Escape output in templates (`htmlspecialchars`) and use prepared statements via PDO/model layer. + +## Testing Guidelines +There is currently no dedicated `tests/` suite in this repository. For each change: +- Lint modified PHP files with `php -l`. +- Run affected flows through UI endpoints and/or cron scripts. +- Verify database-impacting changes with the relevant migration and rollback plan. +- Document manual test steps in the PR. + +## Commit & Pull Request Guidelines +Git history favors Conventional Commit-style prefixes, especially `feat:` (for example: `feat: Integrate DataForSEO...`). Use: +- `feat:`, `fix:`, `refactor:`, `docs:`, `chore:` with concise imperative summaries. +- One logical change per commit; include migration changes in the same commit as dependent code. + +PRs should include: +- Clear scope and risk summary. +- Linked issue/task ID (if available). +- Setup/migration notes (`migrations/00x_*.sql`, `.env` changes). +- Screenshots for template/UI updates (`templates/`, `assets/`).