From 201de67711ba5270f04508408769575567eff31e Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Wed, 30 Mar 2016 14:56:59 +0200 Subject: [PATCH] added a maintenance document --- contributing/code/index.rst | 1 + contributing/code/maintenance.rst | 80 +++++++++++++++++++++++++++++ contributing/code/patches.rst | 10 ++-- contributing/community/releases.rst | 5 ++ contributing/map.rst.inc | 1 + 5 files changed, 93 insertions(+), 4 deletions(-) create mode 100644 contributing/code/maintenance.rst diff --git a/contributing/code/index.rst b/contributing/code/index.rst index ca4664ac802..0fc8241ad46 100644 --- a/contributing/code/index.rst +++ b/contributing/code/index.rst @@ -6,6 +6,7 @@ Contributing Code bugs patches + maintenance core_team security tests diff --git a/contributing/code/maintenance.rst b/contributing/code/maintenance.rst new file mode 100644 index 00000000000..bc16a6cf805 --- /dev/null +++ b/contributing/code/maintenance.rst @@ -0,0 +1,80 @@ +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". + +.. note:: + + When documentation (or phpdoc) is not in sync with the code, code behavior + should always be considered as being the correct one. + +Besides bug fixes, other minor changes can be accepted in a patch version: + +* **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); + +* **Newer versions of PHP/HHVM**: Fixes that add support for newer versions of + PHP or HHVM are acceptable if they don't break the unit test suite; + +* **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; + +* **Translations**: Translation updates and additions are accepted; + +* **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; + +* **Coding standard and refactoring**: Coding standard fixes or code + refactoring are not recommended but can be accepted for consistency with the + existing code base, if they are not too invasive, and if merging them on + master would not lead to complex branch merging; + +* **Tests**: Tests that increase the code coverage can be added. + +Anything not explicitly listed above should be done on the next minor or major +version instead (aka the *master* branch). For instance, the following changes +are never accepted in a patch version: + +* **New features**; + +* **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. + +.. note:: + + This policy is designed to enable a continuous upgrade path that allows one + to move forward with newest Symfony versions in the safest way. One should + be able to move PHP versions, OS or Symfony versions almost independently. + That's the reason why supporting the latest PHP versions or OS features is + considered as bug fixes. diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index f8775ebce77..6335693ac90 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -107,10 +107,12 @@ Choose the right Branch Before working on a patch, you must determine on which branch you need to work: -* ``2.3``, if you are fixing a bug for an existing feature (you may have - to choose a higher branch if the feature you are fixing was introduced - in a later version); -* ``master``, if you are adding a new feature. +* ``2.3``, if you are fixing a bug for an existing feature or want to make a + change that falls into the :doc:`list of acceptable changes in patch versions + ` (you may have to choose a higher branch if + the feature you are fixing was introduced in a later version); + + * ``master``, if you are adding a new feature. .. note:: diff --git a/contributing/community/releases.rst b/contributing/community/releases.rst index 82757be6b5b..f9c52184dcb 100644 --- a/contributing/community/releases.rst +++ b/contributing/community/releases.rst @@ -48,6 +48,11 @@ type of the release. This maintenance is divided into: be fixed. The end of this period is referenced as being the *end of life* of a release. +.. note:: + + The :doc:`maintenance document ` describes + the boundaries of acceptable changes during maintenance. + Symfony Versions ---------------- diff --git a/contributing/map.rst.inc b/contributing/map.rst.inc index 9ec7f507ab0..22f96075c8e 100644 --- a/contributing/map.rst.inc +++ b/contributing/map.rst.inc @@ -3,6 +3,7 @@ * :doc:`Bugs ` * :doc:`Patches ` * :doc:`Reviewing Issues and Patches ` + * :doc:`Maintenance ` * :doc:`The Core Team ` * :doc:`Security ` * :doc:`Tests `