Maintenance

During the lifetime of a minor version, new releases (patch versions) are published on a monthly basis. This document describes the boundaries of acceptable changes.

Bug fixes are accepted under the following conditions:

• The change does not break valid unit tests;
• New unit tests cover the bug fix;
• The current buggy behavior is not widely used as a "feature".

To avoid backward compatibility breaks, we tend to be very strict about changes accepted for patch versions.

Besides bug fixes, other minor changes might be accepted in a patch version on a case by case basis:

• Newer versions of PHP: Fixes that add support for newer versions of PHP are acceptable if they don't break the unit test suite, but we never add support for newer PHP features;
• Newer versions of popular OSes: Fixes that add support for newer versions of popular OSes (Linux, MacOS and Windows) are acceptable if they don't break the unit test suite, but we never add support for newer PHP features or newer versions of OSes;
• Translations: Translation updates and additions are always merged in the oldest maintained branch;
• External data: Updates for external data included in Symfony can be updated (like ICU for instance);
• Version updates for Composer dependencies: Changing the minimal version of a dependency is possible, bumping to a major one or increasing PHP minimal version is not;
• Tests: Tests that increase the code coverage can be added.

The following changes are generally not accepted in a patch version, except on a case by case basis (mostly when this is related to fixing a security issue):

• Performance improvement: Performance improvement should only be accepted if the changes are local (located in one class) and only for algorithmic issues (any such patches must come with numbers that show a significant improvement on real-world code);
• Coding standard and refactoring: Coding standard fixes or code refactoring are almost never accepted except for consistency with the existing code base, if they are not too invasive, and if merging them into higher branches would not lead to complex branch merging.
• Adding new classes or non private methods: While working on a bug fix, never introduce new classes or public/protected methods (or global functions).
• Adding configuration options: Introducing new configuration options is never allowed.
• Adding new deprecations: After a version reaches stability, new deprecations cannot be added anymore.
• Adding or updating annotations: Adding or updating annotations (PHPDoc annotations for instance) is not allowed; fixing them might be accepted.

Anything not explicitly listed above should be done on the next minor or major version instead. For instance, the following changes are never accepted in a patch version:

• New features;
• Security hardening;
• Backward compatibility breaks: Note that backward compatibility breaks can be done when fixing a security issue if it would not be possible to fix it otherwise;
• Support for external platforms: Adding support for new platforms (like Google App Engine) cannot be done in patch versions;
• Exception messages: Exception messages must not be changed as some automated systems might rely on them (even if this is not recommended);
• Adding new Composer dependencies;
• Support for newer major versions of Composer dependencies: Taking into account support for newer versions of an existing dependency is not acceptable.
• Web design: Changing the web design of built-in pages like exceptions, the toolbar or the profiler is not allowed.