PHP RFC: Minor version compatibility

• Version: 0.9
• Date: 2025-04-13
• Author: Jorg Sowa jorg.sowa@gmail.com
• Status: Withdrawn
• First Published at: https://wiki.php.net/rfc/minor-version-compatibility

This RFC aims to clarify and codify the rules regarding backward compatibility and userland API compatibility in PHP minor versions. Currently, there is no formal or widely respected policy for minor version changes, which has led to inconsistent expectations for contributors and users alike. By establishing a clear set of expectations and criteria for what constitutes an acceptable change in a minor release, this RFC seeks to improve predictability and trust in the PHP release cycle.

Several ongoing pull requests have sparked discussions around potential BC breaks, including:

• https://github.com/php/php-src/pull/15647
• https://github.com/php/php-src/pull/15883
• https://github.com/php/php-src/pull/17859

Additionally, some related changes have already been merged:

• https://github.com/php/php-src/pull/12252

Current release versioning from 2010's policy.

Major Version Number

• x.y.z to x+1.0.0
  • Bug fixes
  • New features
  • Extensions support can be ended (moved to PECL)
  • Backward compatibility can be broken
  • API compatibility can be broken (internals and userland)
  • ABI can be broken (internals)

Minor Version Number

• x.y.z to x.y+1.z
  • Bugfixes
  • New features
  • Extensions support can be ended (moved to PECL)
  • Backward compatibility must be kept
  • API compatibility must be kept (userland)
  • ABI and API can be broken (internals)
  • Source compatibility should be kept if possible, while breakages are allowed

Patch Version Number

• x.y.z to x.y.z+1
  • Bug fixes and security patches only
  • Extensions support can't be removed (like move them to PECL)
  • Backward compatibility must be kept (internals and userland)
  • ABI and API compatibility must be kept (internals)

We propose the following unification of the list and clarification of the minor version compatibility policy.

Major Version Number

• x.y.z to x+1.0.0
  • Backward compatibility MAY be broken
  • API compatibility MAY be broken (internals and userland)
  • It MAY include minor and patch level changes.

Minor Version Number

• x.y.z to x.y+1.0
  • New feature MAY be added
  • Extension support MAY be ended (moved to PECL)
  • General backward compatibility SHOULD be kept with the exemptions:
    • ABI and API MAY be broken (internals)
    • Source compatibility SHOULD be kept if possible
    • If API (userland) input validation is changed to reject values previously accepted, a deprecation warning MUST be emitted in the same minor version, and a ValueError MUST be thrown in the next major version.
  • It MAY include patch level changes.

Patch Version Number

• x.y.z to x.y.z+1
  • Bug fixes and security patches
  • Backward compatibility MUST be kept (internals and userland)

This proposal does not introduce any immediate backward-incompatible changes. Instead, it introduces a policy for how backward-incompatible changes must be introduced in a phased and transparent manner in future minor releases.

The changes will apply immediately to the whole PHP release cycle.

The primary vote defines the general rules for backward compatibility (BC) in API versioning. A two-thirds majority (2/3) is required for this vote to pass.

This vote defines the rules for how BC breaks in API input validation should be handled.

If accepted:

If API (userland) input validation is changed to reject values previously accepted, a deprecation warning MUST be emitted in the same minor version, and a ValueError MUST be thrown in the next minor or major version.

If rejected:

If API (userland) input validation is changed to reject values that were previously accepted, a ValueError MAY be raised in the same version.

This vote applies only if the previous vote is accepted. It determines what type of warning should be emitted when input validation behavior is deprecated.

If E_DEPRECATED is chosen:

If API (userland) input validation is changed to reject values previously accepted, a E_DEPRECATED warning MUST be emitted in the same minor version, and a ValueError MUST be thrown in the next major version.

If E_WARNING is chosen:

If API (userland) input validation is changed to reject values previously accepted, an E_WARNING MUST be emitted in the same minor version, and a ValueError MUST be thrown in the next major version.

The implementation of this RFC is a change to the https://github.com/php/policies/blob/main/release-process.rst document: https://github.com/php/policies/pull/15

• Original Release Process RFC: https://wiki.php.net/rfc/releaseprocess
• Existing Release Process Policy document: https://github.com/php/policies/blob/main/release-process.rst
• Discussion on the input validation: https://news-web.php.net/php.internals/126706