added a maintenance document

Author: fabpot

contributing/code/index.rst

@@ -6,6 +6,7 @@ Contributing Code
 
     bugs
     patches
+    maintenance
     core_team
     security
     tests

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.

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
+  </contributing/code/maintenance>` (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::
 

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 </contributing/code/maintenance>` describes
+    the boundaries of acceptable changes during maintenance.
+
 Symfony Versions
 ----------------
 

contributing/map.rst.inc

@@ -3,6 +3,7 @@
   * :doc:`Bugs </contributing/code/bugs>`
   * :doc:`Patches </contributing/code/patches>`
   * :doc:`Reviewing Issues and Patches </contributing/community/reviews>`
+  * :doc:`Maintenance </contributing/code/maintenance>`
   * :doc:`The Core Team </contributing/code/core_team>`
   * :doc:`Security </contributing/code/security>`
   * :doc:`Tests </contributing/code/tests>`