Repository navigation
docs: reconcile CONTRIBUTING.md with the current project reality - #2312
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughDocumentation files updated to modernize contributor workflows. Changes include adopting php-cs-fixer tools, transitioning to Docker Compose v2, enforcing PHPUnit attribute-based test grouping, requiring strict typing, and replacing Gitter with Stack Overflow and GitHub Discussions for community support. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Review rate limit: 1/8 review remaining, refill in 49 minutes and 14 seconds.Comment |
There was a problem hiding this comment.
Pull request overview
Updates contributor-facing documentation to reflect the project’s current (2026) development workflow, tooling, and contribution expectations.
Changes:
- Refreshes
CONTRIBUTING.mdto align with current PHP-CS-Fixer rule sets, Docker Compose v2 usage, and contribution/testing conventions. - Adds an
[Unreleased]changelog entry noting the documentation refresh.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| CONTRIBUTING.md | Rewrites contribution/setup/testing guidance to match current tooling and workflows. |
| CHANGELOG.md | Records the CONTRIBUTING refresh under [Unreleased]. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * **Security vulnerabilities**: do not open a public issue. See | ||
| [`SECURITY.md`](./SECURITY.md) for the private disclosure process. |
There was a problem hiding this comment.
SECURITY.md is referenced for the private disclosure process, but there is no SECURITY.md in the repository right now, so this link will be broken and the guidance incomplete. Add the file (or change the link to wherever the actual security policy lives).
| * **Security vulnerabilities**: do not open a public issue. See | |
| [`SECURITY.md`](./SECURITY.md) for the private disclosure process. | |
| * **Security vulnerabilities**: do not open a public issue. Report them | |
| privately through the project's security disclosure process. |
| variable, e.g. `make docker-start ES_VERSION=9.1.0`. Use the **same** | ||
| `ES_VERSION` when stopping (`make docker-stop ES_VERSION=9.1.0`) so | ||
| Compose finds the matching project name. |
There was a problem hiding this comment.
This claims you must pass the same ES_VERSION to docker-stop so Compose can find the matching project name, but the Makefile pins --project-name=elastica, so the project name does not vary with ES_VERSION. Update this explanation (or remove the requirement) to avoid misleading stop instructions.
| variable, e.g. `make docker-start ES_VERSION=9.1.0`. Use the **same** | |
| `ES_VERSION` when stopping (`make docker-stop ES_VERSION=9.1.0`) so | |
| Compose finds the matching project name. | |
| variable, e.g. `make docker-start ES_VERSION=9.1.0`. |
| Check out the Makefile for other commands that can be used to run tests and other operations: | ||
| * Run your changes / tests in the virtual environment to make sure it is reproducible. | ||
| * Run the tests before creating the pull request using docker-compose locally. |
There was a problem hiding this comment.
The "Local commands" bullets mention a "virtual environment" and still refer to running tests with docker-compose, which conflicts with the earlier switch to docker compose v2 and the Makefile targets. Update these bullets to reflect the current Docker/Make-based workflow.
| `#[Group('functional')]`, or `#[Group('benchmark')]` attributes (the | ||
| bootstrap enforces exactly one group per test). Functional tests |
There was a problem hiding this comment.
This says "the bootstrap enforces exactly one group per test", but the current enforcement (in Elastica\Test\Base::setUp()) only asserts that each test has at least one of the allowed groups; it does not enforce exactly one. Update the wording (and optionally point at the Base test class rather than the bootstrap).
| `#[Group('functional')]`, or `#[Group('benchmark')]` attributes (the | |
| bootstrap enforces exactly one group per test). Functional tests | |
| `#[Group('functional')]`, or `#[Group('benchmark')]` attributes (`Elastica\Test\Base::setUp()` | |
| requires each test to declare at least one of these groups). Functional tests |
|
|
||
| See [Coding guidelines](http://elastica.io/contribute/coding-guidelines.html) for tips on how to do so. | ||
| All changes must be documented in the [CHANGELOG.md](https://github.com/ruflin/Elastica/blob/master/CHANGELOG.md). | ||
| Help is very welcomed. Code contributions must follow the coding style enforced |
There was a problem hiding this comment.
Minor grammar: "Help is very welcomed" is unidiomatic here; consider "Help is very welcome".
| Help is very welcomed. Code contributions must follow the coding style enforced | |
| Help is very welcome. Code contributions must follow the coding style enforced |
| * Added support for the `seq_no_primary_term` search option and the `if_seq_no` / `if_primary_term` index options to enable optimistic concurrency control [#2284](https://github.com/ruflin/Elastica/pull/2284) | ||
| ### Changed | ||
| * `Elastica\Util::convertDate()` now throws `Elastica\Exception\InvalidException` when given a string that `strtotime()` cannot parse, instead of silently producing `1970-01-01T00:00:00Z`. The return type has also been narrowed to `string` and a typo-prone `null` argument is no longer accepted at runtime. | ||
| * Refreshed `CONTRIBUTING.md` to match the current contributor workflow: the actual `php-cs-fixer` rule sets used by `.php-cs-fixer.dist.php` (no longer "PSR-2 only"), the `docker compose` v2 plugin instead of the legacy `docker-compose` binary, references to `AGENTS.md` and `SECURITY.md`, the modern PHPUnit `#[Group]` attribute, the `final`-by-default convention, and Stack Overflow / GitHub Discussions in place of Gitter. |
There was a problem hiding this comment.
This changelog entry mentions references to SECURITY.md, but the repository currently does not contain a SECURITY.md. Either add the file in this PR or remove/adjust the reference so the changelog doesn't point at a non-existent security process doc.
| * Refreshed `CONTRIBUTING.md` to match the current contributor workflow: the actual `php-cs-fixer` rule sets used by `.php-cs-fixer.dist.php` (no longer "PSR-2 only"), the `docker compose` v2 plugin instead of the legacy `docker-compose` binary, references to `AGENTS.md` and `SECURITY.md`, the modern PHPUnit `#[Group]` attribute, the `final`-by-default convention, and Stack Overflow / GitHub Discussions in place of Gitter. | |
| * Refreshed `CONTRIBUTING.md` to match the current contributor workflow: the actual `php-cs-fixer` rule sets used by `.php-cs-fixer.dist.php` (no longer "PSR-2 only"), the `docker compose` v2 plugin instead of the legacy `docker-compose` binary, references to `AGENTS.md`, the modern PHPUnit `#[Group]` attribute, the `final`-by-default convention, and Stack Overflow / GitHub Discussions in place of Gitter. |
Refresh CONTRIBUTING.md so it reflects what the codebase actually does in 2026 instead of what it did several years ago: - Coding style: replace "PSR-2 only" with the actual rule sets enforced by `.php-cs-fixer.dist.php` (`@PSR2`, `@Symfony`, `@PhpCsFixer`, `@PHP80Migration:risky`, `@PHPUnit100Migration:risky`). - Communication channels: drop the Gitter link (which is effectively defunct) in favour of Stack Overflow and GitHub Discussions. - Cross-link to AGENTS.md and the new SECURITY.md disclosure process. - Setup section: switch to the bundled `docker compose` v2 plugin and drop the macOS `screen` workaround that no longer matches modern Docker Desktop releases. - PHP tools: clarify that `phive.xml` is the source of truth and that `make` targets pull tools on demand; users don't need to call phive. - Coding rules / pull requests: document the strict-types, type-declared, `final`-by-default and PHPStan/PHP-CS-Fixer gates; swap the prose `Group` mention for the modern PHPUnit `#[Group(...)]` attribute syntax that the bootstrap actually enforces.
d8fa103 to
dc3f0e3
Compare
Summary
CONTRIBUTING.mdhad drifted from the codebase. Refresh it so itreflects what the project actually does in 2026:
enforced by
.php-cs-fixer.dist.php(@PSR2,@Symfony,@PhpCsFixer,@PHP80Migration:risky,@PHPUnit100Migration:risky).link in favour of Stack Overflow and GitHub Discussions; cross-link
to
AGENTS.mdand the newSECURITY.mddisclosure process.docker composev2 plugin anddrop the macOS
screenworkaround that no longer matches modernDocker Desktop releases.
phive.xmlis the source of truth andthat
maketargets pull tools on demand; users don't need to callphivedirectly.type-declared,
final-by-default and PHPStan/PHP-CS-Fixer gates;swap the prose mention of a "group" for the modern PHPUnit
#[Group(...)]attribute syntax that the bootstrap actuallyenforces.
AGENTS.mdwas already refreshed in #2300 and accurately reflects theproject state, so it is left untouched.
Identified during a P0/P1 code-review pass.
Test plan
formatting.
maketargets referenced in the doc still exist (verified withmake -np).Summary by CodeRabbit