WIP: maintenance workflow documentation

source/contribute/maintainer.rst

@@ -22,6 +22,14 @@ following:
 -  Creating release branches.
 -  Tagging released versions within **master** and release branches.
 
+Automation
+----------
+
+Each of the following steps are documented for humans to perform them
+manually, but maintainers and contributors are highly encouraged to try
+and automate them away into tooling that is commonly available across
+the organisation projects, as well as the community at large.
+
 Setup
 -----
 
@@ -31,7 +39,7 @@ locally:
 
 .. code-block:: console
 
-    $ git clone git@github.com:username/doctrine2.git doctrine2-orm
+    $ git clone git@github.com:<username>/doctrine2.git doctrine2-orm
     $ cd doctrine2-orm
 
 Fetch dependencies using `composer <https://getcomposer.org/>`_:
@@ -59,16 +67,167 @@ Optionally, add any additional contributor/maintainer forks, e.g.:
 
     $ git remote add romanb git://github.com/romanb/doctrine2.git
 
+You can also fetch all open pull requests via `git fetch` if you
+edit your ``.git/config`` as following:
+
+... code-block:: console
+
+    [remote "doctrine"]
+        url = git@github.com:doctrine/doctrine2.git
+        fetch = +refs/heads/*:refs/remotes/doctrine/*
+        # add this:
+        fetch = +refs/pull/*/head:refs/remotes/doctrine/pr/*
+
+Distinguishing features, bugs and critical fixes
+------------------------------------------------
+
+The primary role of a maintainer, besides being also a contributor,
+is to sort incoming proposals by their category:
+
+-  **new features** are additions that provide new API or new behavior
+   that was previously not exposed by the project
+-  **improvements** are additions that improve existing API by making
+   it more clear, by improving the usability and performance, or by
+   verifying existing behavior via refactoring, new tests or static
+   analysis.
+-  **bug fixes** are changes to the codebase that do correct invalid
+   behaviour.
+-  **critical fixes** are changes to the codebase that correct invalid
+   behavior that was erroneously introduced, and prevents installation
+   or usage of the library by a very large portion of the community.
+-  **security fixes** are changes to the codebase that correct existing
+   behavior in the codebase that may lead to substantial financial or
+   personal damage to consumers of the packages due to malicious
+   attack vectors.
+-  **deprecations** are changes to the codebase that do mark existing
+   API as "to be removed in future"
+-  **backwards-compatibility breakages** (or **BC breaks** in short)
+   are modifications to the existing API or implementation that would
+   result in downstream users having to correct their software to
+   adapt to the new changes. Maintainers should also prevent any
+   unnecessary BC breaks, and always evaluating if it is worth
+   introducing them.
+
+Stability and Semantic Versioning
+---------------------------------
+
+A maintainer must also always consider that any proposal, regardless
+how well tested and verified it could be, brings in some instability.
+In order to reduce the amount of defects and/or regressions reaching
+downstream users, a maintainer must therefore always consider
+carefully where a patch may land.
+
+Packages controlled by the Doctrine organisation are to follow
+`Semantic Versioning (SemVer) <https://semver.org/spec/v2.0.0.html>`_
+rules, with the famous ``MAJOR.MINOR.PATCH`` naming scheme.
+
+This effectively means:
+
+- **PATCH** only contains **bug fixes**, **security fixes** and
+  **critical fixes**
+- **MINOR** can contain everything that is in **PATCH** plus
+  **new features**, **improvements** and **deprecations**
+- **MAJOR** can contain all of the above plus **BC breaks**
+
+Whilst it is possible to automate some of these decisions, humans
+are still better at categorising these changes due to the amount of
+nuances that are involved in the software development process.
+
 Branching Model
 ---------------
 
-Merging topic branches:
+In order to maintain all the stability invariants that SemVer imposes,
+it is vital that maintainers know where to merge incoming patches.
+
+Packages in the doctrine organisation should use following branching
+structure:
+
+ * ``develop`` - extremely unstable, points at the next planned
+   **MAJOR** release, may be rebased in order to speed up individual
+   maintainers prototyping new changes. Changes on ``develop`` can
+   be radical, and should not be relied upon.
+ * ``master`` - always to be considered as the next planned **MAJOR**
+   or **MINOR** release (depending on team internal agreement).
+   Consumers should not rely on ``master`` unless they are prepared
+   to adapt their codebase at every potentially breaking change.
+ * ``MAJOR.MINOR.x`` - always to be considered the next planned
+   **PATCH** release. Maintainers should keep these (multiple) branches
+   stable. The base of these branches MUST be the ``MAJOR.MINOR.0`` tag.
+   Without a pre-existing tag, these branches should not exist
+
+Releasing packages
+------------------
+
+**MAJOR.0.0** and **MAJOR.MINOR.0** releases **MUST** be tagged from
+``master``.
+
+When tagging a new **MAJOR.0.0** or **MAJOR.MINOR.0** release, a
+corresponding **MAJOR.MINOR.x** branch should be branched off the tag.
+
+**MAJOR.MINOR.1+** releases must be tagged from the corresponding
+``MAJOR.MINOR.x`` branch.
+
+This effectively means that a typical doctrine package should have a
+git graph like following:
+
+.. code-block:: console
+
+                                             ----- develop
+                                            /
+    1.0.0 ----- 1.1.0 ----- 2.0.0 ------ master
+      |           |           \
+      |           |            ----- 2.0.x
+      |           \
+      |            ----- 1.1.1 ----- 1.1.2 ----- 1.1.x
+      \
+       ----- 1.0.1 ----- 1.0.2 ----- 1.0.x
+
+Preparing a release
+-------------------
 
--  Topic branches **must** merge into **master** and/or any affected
-   release branches.
--  Merging a topic branch puts it into the *next* release, that is the
-   next release created from **master** and/or the next patch release
-   created from a specific release branch.
+Assuming that all tasks for a planned release are completed, a
+maintainer would then be in the position of preparing a git tag,
+which for doctrine project also corresponds to a release.
+
+To do that:
+
+-  ensure that all known introduced **BC Breaks** are documented
+   in ``UPGRADE.md``.
+-  ensure that the automated tests for the branch from which
+   a release has to be tagged are passing.
+-  prepare a release description, which should:
+    -  list all patches
+    -  describe the points of major relevance in the patch
+   maintainers may want to use a tool such
+   as `weierophinney/changelog_generator <https://github.com/weierophinney/changelog_generator>`_
+   or `jwage/changelog-generator <https://github.com/jwage/changelog-generator>`_)
+   in order to generate such release notes
+
+Then it is possible to tag a release.
+
+Please note that tags *MUST* be signed. Unsigned releases will be
+removed and replaced.
+
+For a new patch release,
+this is the workflow (here with **MAJOR** = 5, **MINOR** = 3 and **PATCH** = 1):
+
+.. code-block:: console
+
+    $ git checkout 5.3.x
+    $ git pull --ff-only
+    $ git tag -s 5.3.1 -F my-release-notes.txt --cleanup=verbatim
+    $ git push origin 5.3.1
+
+To release a new minor or major version, the workflow starts from
+``master``:
+
+.. code-block:: console
+
+    $ git checkout master
+    $ git pull --ff-only
+    $ git tag -s 6.2.0 -F my-release-notes.txt --cleanup=verbatim
+    $ git checkout -b 6.2.x
+    $ git push origin 6.2.0 6.2.x
 
 Configuring Remotes
 -------------------