Document the BC/versioning policy, pair @internal with @psalm-internal, and make the BC check branch-aware

[MidnightDesign]

Summary

Establishes the project's backward-compatibility and versioning policy, fixes the @internal surface so the break-detector reads it correctly, and wires that detector to match how the branches are used.

1. BC/versioning policy — docs/BACKWARD-COMPATIBILITY.md

Defines the public surface as every public symbol not marked @internal, the pre-1.0 rule that the minor is the compatibility boundary, the split between structural and behavioral breaks, how the check runs, and how the version is chosen and recorded.

2. @internal hygiene + a lint

Delimiters and TypeParser carried @psalm-internal but not @internal, so Roave (which only recognizes @internal) treated them as public API. This pairs them and adds InternalAnnotationConsistencyTest — a file-scanning guard (same style as the existing BuiltinFunctionsTest) that fails if any @psalm-internal symbol lacks @internal, keeping the surface from drifting again.

3. Branch-aware BC check

The Backward Compatibility job runs Roave as:

• informational on master and feature branches — during a pre-release minor cycle the trunk intentionally accumulates the next version's breaks, so a reported break there is expected;
• blocking on maintenance branches (*.x, e.g. 0.3.x), which promise compatibility.

Implemented via continue-on-error: ${{ !endsWith(github.base_ref, '.x') }}.

Validation

PHPUnit (1030 tests), PHP CS Fixer, PHPStan, and Psalm all pass locally. Infection is unaffected — the only src changes are docblock lines (no mutations), and the new test lives in tests/. Roave itself only runs in CI.

Notes

• Base is master; independent of Point Dependabot at master and document the trunk-based release model #89 (RELEASING.md), which this doc cross-references.
• Marking the two classes @internal is itself a structural change Roave will report on master — expected and informational during the 0.2 → 0.3 window.

🤖 Generated with Claude Code