Skip to content

docs: reconcile CONTRIBUTING.md with the current project reality - #2312

Merged
ruflin merged 1 commit into
9.xfrom
docs/sync-agents-contributing
Oct 23, 2026
Merged

ruflin merged 1 commit into
9.xfrom
docs/sync-agents-contributing

Conversation

@ruflin

@ruflin ruflin commented Apr 30, 2026 •

Copy link
Copy Markdown
Owner

Summary

CONTRIBUTING.md had drifted from the codebase. Refresh it so it
reflects what the project actually does in 2026:

  • 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 (effectively defunct) Gitter
    link in favour of Stack Overflow and GitHub Discussions; cross-link
    to AGENTS.md and the new SECURITY.md disclosure process.
  • Setup — 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 directly.
  • Coding rules / pull requests — document the strict-types,
    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 actually
    enforces.

AGENTS.md was already refreshed in #2300 and accurately reflects the
project state, so it is left untouched.

Identified during a P0/P1 code-review pass.

Test plan

  • No code changes; rendered the file in GitHub preview to confirm
    formatting.
  • make targets referenced in the doc still exist (verified with
    make -np).

Summary by CodeRabbit

  • Documentation
    • Refreshed contributor workflow documentation with updated guidelines
    • Migrated Docker setup instructions to Docker Compose v2
    • Updated contributor communication channels to Stack Overflow and GitHub Discussions
    • Enhanced coding standards including strict typing requirements and test organization
    • Improved issue workflow with dedicated guidance for bug reports and security vulnerabilities

Copilot AI review requested due to automatic review settings April 30, 2026 21:14
@coderabbitai

coderabbitai Bot commented Apr 30, 2026 •

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 780d5315-b34f-4eb2-b86d-bff35ad94b0a

📥 Commits

Reviewing files that changed from the base of the PR and between bbd7828 and d8fa103.

📒 Files selected for processing (2)
  • CHANGELOG.md
  • CONTRIBUTING.md

📝 Walkthrough

Walkthrough

Documentation 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

Cohort / File(s) Summary
Documentation Updates
CHANGELOG.md
Added unreleased changelog entry summarizing contributor workflow refreshes including php-cs-fixer rules, Docker Compose v2 adoption, PHPUnit attributes, and community channel changes.
Contributor Guidelines
CONTRIBUTING.md
Substantially revised contributor documentation: overhauled Issues workflow (added security vulnerability guidance, replaced Gitter), updated Docker setup to Docker Compose v2 with Compose file descriptions, clarified php-cs-fixer and tool management via phive.xml, added strict typing and PHPUnit #[Group] attribute requirements, specified BC-break documentation, and updated namespace/class naming guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

Poem

🐰 Fresh paths for contributors to explore,
Docker v2 and php-cs-fixer galore,
PHPUnit groups now marked with care,
Stack Overflow winds fill the air!
Workflow refreshed, documentation gleams bright,
The contributor garden now feels just right! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately and clearly describes the main objective of the PR: reconciling CONTRIBUTING.md documentation with current project practices and reality.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/sync-agents-contributing

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
Review rate limit: 1/8 review remaining, refill in 49 minutes and 14 seconds.

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

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates contributor-facing documentation to reflect the project’s current (2026) development workflow, tooling, and contribution expectations.

Changes:

  • Refreshes CONTRIBUTING.md to 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.

Comment thread CONTRIBUTING.md
Comment on lines +21 to +22
* **Security vulnerabilities**: do not open a public issue. See
[`SECURITY.md`](./SECURITY.md) for the private disclosure process.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
* **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.

Copilot uses AI. Check for mistakes.
Comment thread CONTRIBUTING.md
Comment on lines +45 to +47
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.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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`.

Copilot uses AI. Check for mistakes.
Comment thread CONTRIBUTING.md
Comment on lines 65 to 67
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.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
Comment thread CONTRIBUTING.md
Comment on lines +165 to +166
`#[Group('functional')]`, or `#[Group('benchmark')]` attributes (the
bootstrap enforces exactly one group per test). Functional tests

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
`#[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

Copilot uses AI. Check for mistakes.
Comment thread CONTRIBUTING.md

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

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor grammar: "Help is very welcomed" is unidiomatic here; consider "Help is very welcome".

Suggested change
Help is very welcomed. Code contributions must follow the coding style enforced
Help is very welcome. Code contributions must follow the coding style enforced

Copilot uses AI. Check for mistakes.
Comment thread CHANGELOG.md
* 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.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
* 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.

Copilot uses AI. Check for mistakes.
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.
@ruflin
ruflin force-pushed the docs/sync-agents-contributing branch from d8fa103 to dc3f0e3 Compare October 23, 2026 13:28
@ruflin
ruflin merged commit 3e56f4b into 9.x Oct 23, 2026
28 of 29 checks passed
@ruflin
ruflin deleted the docs/sync-agents-contributing branch October 23, 2026 21:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants