[DX] Improve AI contribution guidelines by Rafikooo · Pull Request #18708 · Sylius/Sylius

Rafikooo · 2026-01-07T14:01:39Z

Expands AGENTS.md with practical reference paths and fills previously empty sections.

Changes:

Add Reference Files section with paths to entities, API Platform configs, services, templates, tests, and migrations
Document migration requirements: always create both MySQL and PostgreSQL versions
Fill PHPUnit, Behat, JavaScript sections with guidelines
Add Common Mistakes to Avoid section
Condense intro and remove redundant points

coderabbitai · 2026-01-07T14:02:07Z

📝 Walkthrough

Walkthrough

Documentation restructuring of AGENTS.md that expands and reorganizes AI contribution guidelines with new sections on reference file patterns, testing conventions, frontend standards, and common pitfalls.

Changes

Cohort / File(s)	Summary
AI Contribution Guidelines Documentation `AGENTS.md`	Restructured and expanded with new Reference Files section detailing entity, API Platform, service, template, test, and migration patterns; expanded General Guidelines across multiple domains; added comprehensive testing guidelines (Unit/Functional/API/Behat) with naming conventions; augmented frontend guidance with JavaScript and CSS standards; introduced Common Mistakes to Avoid section with repository locations for fixes

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Add initial AGENTS.md #18156: Introduced the initial AGENTS.md file; this PR expands and restructures the guidelines with comprehensive pattern documentation and testing conventions.

Suggested reviewers

GSadee
Wojdylak

Poem

🐰 Hop, hop, guidelines take flight,
Agents now see patterns so bright,
From tests to templates, mistakes to avoid,
Documentation's void is now deploid!
Structured and clear, a roadmap of cheer,
AI assistants will hold this dear. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[DX] Improve AI contribution guidelines' directly relates to the main change: expanding and improving the AGENTS.md documentation for AI assistants. It accurately summarizes the primary objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @AGENTS.md:
- Around line 34-39: Update the Migrations location line to show the concrete
filename pattern used by the codebase: replace
`src/Sylius/Bundle/CoreBundle/Migrations/` with
`src/Sylius/Bundle/CoreBundle/Migrations/Version[TIMESTAMP].php` and include an
example like `Version20251126120001.php`, keeping the existing notes about
creating two migrations and extending AbstractMigration /
AbstractPostgreSQLMigration to guide developers to the required filename format.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 84b970e and b621fc8.

📒 Files selected for processing (1)

AGENTS.md

🧰 Additional context used

🧠 Learnings (12)

📓 Common learnings

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T05:49:02.960Z
Learning: See AGENTS.md for coding guidelines

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T05:48:59.242Z
Learning: Refer to and follow guidelines documented in the global AGENTS.md file located at the project root

📚 Learning: 2025-11-25T05:49:02.960Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T05:49:02.960Z
Learning: See AGENTS.md for coding guidelines

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:48:59.242Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T05:48:59.242Z
Learning: Refer to and follow guidelines documented in the global AGENTS.md file located at the project root

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Follow the Sylius Backward Compatibility (BC) policy

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/{admin,shop}/**/*.php : For API configuration, use API Platform 4.x

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/*Test.php : Use PHPUnit for unit and functional testing

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/*.php : Do not use deprecated features from PHP, Symfony, or Sylius

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/*.feature : Use Behat for behavior-driven scenarios

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/*.{php,twig} : Follow secure coding practices to prevent XSS, CSRF, injections, auth bypasses, etc.

Applied to files:

AGENTS.md

📚 Learning: 2025-05-13T09:09:07.413Z

Learnt from: Prometee
Repo: Sylius/Sylius PR: 17983
File: src/Sylius/Bundle/InventoryBundle/phpunit.xml.dist:14-14
Timestamp: 2025-05-13T09:09:07.413Z
Learning: In Sylius projects, PHPUnit schema references should use the local vendor file path (`vendor/phpunit/phpunit/phpunit.xsd`) instead of remote URLs (`http://schema.phpunit.de/x.y/phpunit.xsd`) in phpunit.xml.dist files, matching the convention used across Sylius components.

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/*.scss : Avoid `!important` unless absolutely necessary in stylesheets

Applied to files:

AGENTS.md

📚 Learning: 2025-11-25T05:49:22.765Z

Learnt from: CR
Repo: Sylius/Sylius PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T05:49:22.765Z
Learning: Applies to **/*.php : Use PHPDoc only when necessary (e.g., `var Collection<ProductInterface>`) in PHP

Applied to files:

AGENTS.md

🔇 Additional comments (6)

AGENTS.md (6)

41-73: General Guidelines and Commands sections look good.

The sections appropriately reference the BC policy, API Platform 4.x, security practices, and provide practical command examples. Alignment with learnings and Sylius conventions appears solid.

114-131: PHPUnit and Behat sections are well-structured.

The expanded sections provide clear directory patterns, naming conventions, and practical examples. Good alignment with learnings on testing frameworks.

132-149: Frontend sections provide clear standards.

JavaScript and CSS sections appropriately emphasize TypeScript, Stimulus controllers, SCSS-only approach, and modular styling. Good alignment with Bootstrap 5 and project conventions.

150-157: Common Mistakes section is a valuable addition.

This new section efficiently captures frequent pitfalls with concrete references and remediation guidance. Particularly valuable are the architectural distinction (line 156) and the explicit migration/mapping reminders. This will help reduce common onboarding issues.

74-95: No issues found. The PHP 8.2+ requirement specified in the coding standards matches the project's composer.json configuration ("php": "^8.2"), confirming the guideline is accurate and current.

17-18: The paths shown in AGENTS.md lines 17-18 are accurate. API Platform resources are correctly located at src/Sylius/Bundle/ApiBundle/Resources/config/api_platform/resources/admin/Product.xml and resources/shop/Product.xml, following the bundle-based pattern. The abbreviated paths in the documentation are consistent with the style used throughout the section.

Likely an incorrect or invalid review comment.

coderabbitai · 2026-01-07T14:06:27Z

AGENTS.md

+### Migrations
+- Location: `src/Sylius/Bundle/CoreBundle/Migrations/`
+- **ALWAYS create TWO migrations**: one for MySQL, one for PostgreSQL
+- MySQL: extend `Sylius\Bundle\CoreBundle\Doctrine\Migrations\AbstractMigration`
+- PostgreSQL: extend `Sylius\Bundle\CoreBundle\Doctrine\Migrations\AbstractPostgreSQLMigration`
+- When reviewing PRs that touch migrations, verify both versions exist


⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash # Search for AbstractMigration and AbstractPostgreSQLMigration class definitions echo "=== Searching for AbstractMigration ===" find . -type f -name "*.php" -exec grep -l "class AbstractMigration" {} \; | head -10 echo -e "\n=== Searching for AbstractPostgreSQLMigration ===" find . -type f -name "*.php" -exec grep -l "class AbstractPostgreSQLMigration" {} \; | head -10 echo -e "\n=== Checking migration file patterns in CoreBundle ===" find . -path "*/CoreBundle/Migrations/*.php" -type f | head -20 echo -e "\n=== Checking full path structure ===" find . -path "*/Migrations/*.php" -type f | grep -i core | head -15

Repository: Sylius/Sylius

Length of output: 2807

🏁 Script executed:

cat -n AGENTS.md | sed -n '30,45p'

Repository: Sylius/Sylius

Length of output: 786

Add concrete migration filename example with version prefix.

The class names AbstractMigration and AbstractPostgreSQLMigration are correct. However, line 35 should include a concrete filename example. All migrations in the codebase use the pattern VersionYYYYMMDDHHMMSS.php (e.g., Version20251126120001.php). Update the location line to show: src/Sylius/Bundle/CoreBundle/Migrations/Version[TIMESTAMP].php or provide a specific example to guide developers on the required filename format.

🤖 Prompt for AI Agents

In @AGENTS.md around lines 34 - 39, Update the Migrations location line to show the concrete filename pattern used by the codebase: replace `src/Sylius/Bundle/CoreBundle/Migrations/` with `src/Sylius/Bundle/CoreBundle/Migrations/Version[TIMESTAMP].php` and include an example like `Version20251126120001.php`, keeping the existing notes about creating two migrations and extending AbstractMigration / AbstractPostgreSQLMigration to guide developers to the required filename format.

AGENTS.md

…erns

Rafikooo requested review from a team as code owners January 7, 2026 14:01

probot-autolabeler bot added the Maintenance CI configurations, READMEs, releases, etc. label Jan 7, 2026

coderabbitai bot reviewed Jan 7, 2026

View reviewed changes

loic425 reviewed Jan 9, 2026

View reviewed changes

AGENTS.md Outdated Show resolved Hide resolved

[DX] Improve AI contribution guidelines with reference files and patt…

f3c4454

…erns

Rafikooo force-pushed the improve-agents-md-guidelines branch from b621fc8 to f3c4454 Compare January 9, 2026 13:48

GSadee approved these changes Jan 19, 2026

View reviewed changes

GSadee added the DX Issues and PRs aimed at improving Developer eXperience. label Jan 19, 2026

GSadee merged commit 75b0d77 into Sylius:2.2 Jan 19, 2026
3 checks passed

coderabbitai bot mentioned this pull request Jan 20, 2026

[UPMERGE] 2.2 -> 2.3 #18737

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[DX] Improve AI contribution guidelines#18708

[DX] Improve AI contribution guidelines#18708
GSadee merged 1 commit intoSylius:2.2from
Rafikooo:improve-agents-md-guidelines

Rafikooo commented Jan 7, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 7, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot Jan 7, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Rafikooo commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Rafikooo commented Jan 7, 2026 •

edited

Loading

coderabbitai bot commented Jan 7, 2026 •

edited

Loading