Contributing

Thanks for helping! The most useful bug reports name what you did, in order, and what the page showed, with the smallest entities and CRUD controllers that show it. Please open an issue; the templates ask for the versions involved. Pull requests get a checklist that matches the ground rules below.

Setup

You need PHP 8.4 or later with pdo_sqlite, Composer and Node 20 or later. The tests need no database server: the test application runs on SQLite.

git clone https://github.com/janalis/easyadmin-embedded-list
cd easyadmin-embedded-list
make install           # Composer and npm
npm ci --prefix docs   # markdownlint and the documentation site
make verify

make serve runs the test application on http://127.0.0.1:8740/admin (admin / admin).

Make targets

make help lists them all.

Target	What it does
make install	composer install and npm ci.
make verify	Definition of done: validate, fmt-check, lint, analyze, test, lint-js and test-js.
make validate	composer validate --strict.
make fmt / make fmt-check	Apply Mago's formatting and Biome's fixes / check Mago's formatting.
make lint	Mago's linter, markdownlint, editorconfig-checker and actionlint. Set a tool's variable empty to skip it (make lint MDLINT=).
make analyze	Mago's static analysis.
make test	Every PHPUnit suite (PHPUNIT_ARGS="--filter …"); make test-unit and make test-functional run one.
make test-js / make lint-js	Vitest / Biome.
make coverage	PHPUnit with PCOV coverage (HTML in var/coverage) and Vitest with coverage; both require 100%.
make infection	Mutation testing of src/ and tools/ against every PHPUnit suite, reports in var/infection/.
make app-setup / make serve / make e2e	Prepare the test application, serve it, or run the Playwright scenarios against it (ARGS="-g …").
make docs / make docs-dev	Build or serve this site.
make release-notes	Print the notes the next release would publish (BUMP=patch, minor, major or X.Y.Z), without touching CHANGELOG.md.
make clean	Remove caches, reports and generated test application files.

Code style

Files	Tool	Rules
PHP	Mago	mago.toml: formatting (120 columns), linting with the Symfony and PHPUnit integrations, and static analysis over src, tests, config and tools.
JavaScript	Biome	biome.json: two spaces, single quotes, semicolons, 120 columns.
Markdown	markdownlint	.markdownlint-cli2.jsonc: the default rules, without line length, inline HTML and code-span spacing checks.
All text files	editorconfig-checker	.editorconfig: UTF-8, LF, final newline, no trailing whitespace; four spaces in PHP and Twig, two in JavaScript, YAML and Markdown, tabs in Makefile.
GitHub workflows	actionlint	Workflow syntax and expressions. Third-party actions are pinned to a commit.

• Fix findings rather than silencing them; no new baseline entries.
• Prose uses US English.
• In PHP, import classes with use.
• The script ships as written: no bundler, no transpiler, no polyfills, and no imports, so hosts need no import map entry for it.

Ground rules

• Upstream EasyAdmin, unchanged. The bundle works through EasyAdmin's extension points: a field, a form type, a field configurator, a kernel.view listener and templates. The one read of EasyAdmin's internals (the template registry, in FragmentListener) is covered by the functional tests on every supported version.
• Tests come with the change. Every changed PHP behavior has PHPUnit coverage and every changed line of the script Vitest coverage; a change to what the page shows gets a Playwright scenario.
• The contract is shared. Headers, markup attributes, events and the EasyAdmin ids the script reads are listed in docs/internals/contract.md. Change them together.
• Configuration and docs move together. A new option gets its ->info() in the configuration tree, a line in Configuration, and a changelog line.
• Changelog: record every user-visible change under ## [Unreleased] in CHANGELOG.md.
• Documentation describes current behavior, in the present tense.

Where to go next

• Architecture: what lives where, and a list request end to end.
• Testing: the suites and the test application.
• Releasing: cutting a version and publishing the site.