From 38f9102147c20fff53937f25f494fb61cc76c317 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 14:22:27 +0200 Subject: [PATCH 01/20] Removed ambiguous `username` URI bit - replaced with a more obvious placholder --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index e0c5c641..17865feb 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -31,7 +31,7 @@ locally: .. code-block:: console - $ git clone git@github.com:username/doctrine2.git doctrine2-orm + $ git clone git@github.com:/doctrine2.git doctrine2-orm $ cd doctrine2-orm Fetch dependencies using `composer `_: From 1922293599c0f2f0a1165b172babf2a2092934b3 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 14:22:52 +0200 Subject: [PATCH 02/20] Documenting that maintainers can fetch all active pull requests by tweaking remotes --- source/contribute/maintainer.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 17865feb..f2986d5c 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -59,6 +59,18 @@ 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/* + + Branching Model --------------- From 6d936fd2e34aa1f355ef126f554c43840e6c1499 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 14:43:53 +0200 Subject: [PATCH 03/20] Documenting primary responsibility of a maintainer to detect and categorise change types --- source/contribute/maintainer.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index f2986d5c..ea9b8de5 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -70,6 +70,26 @@ edit your ``.git/config`` as following: # 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. +- **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. Branching Model --------------- From a0a93bfd07e871a9df1d75f18f406bd23e916be7 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 14:47:02 +0200 Subject: [PATCH 04/20] Documenting what a critical fix is --- source/contribute/maintainer.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index ea9b8de5..9d511c7b 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -84,6 +84,9 @@ is to sort incoming proposals by their category: 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. - **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) From 25f9130652723ae85ff392bd3c407704feee9663 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 14:48:57 +0200 Subject: [PATCH 05/20] Documenting security fixes --- source/contribute/maintainer.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 9d511c7b..8db5cc8b 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -87,6 +87,10 @@ is to sort incoming proposals by their category: - **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) From d81baf3b8599086e0beda370aac5785bf82e7965 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 15:26:51 +0200 Subject: [PATCH 06/20] Documenting stability purpose --- source/contribute/maintainer.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 8db5cc8b..e44372b9 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -98,6 +98,31 @@ is to sort incoming proposals by their category: result in downstream users having to correct their software to adapt to the new changes. +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 `_ 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 --------------- From 9e2eee8a24252a816f4a76d6dd93893d0e9ac40a Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 15:38:57 +0200 Subject: [PATCH 07/20] Maintainers should always evaluate whether a BC break is worth it --- source/contribute/maintainer.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index e44372b9..81d21433 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -96,7 +96,9 @@ is to sort incoming proposals by their category: - **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. + 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 --------------------------------- From fef66f75d373458d8a945c68876cf4bdcb94cd46 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 15:40:27 +0200 Subject: [PATCH 08/20] Clarifying that `Semantic Versioning` = `SemVer` --- source/contribute/maintainer.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 81d21433..2d5f35d6 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -110,8 +110,8 @@ 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 `_ rules, -with the famous ``MAJOR.MINOR.PATCH`` naming scheme. +`Semantic Versioning (SemVer) `_ +rules, with the famous ``MAJOR.MINOR.PATCH`` naming scheme. This effectively means: From 1e2f8122bec355a2842bd4ed89352684c158f9b5 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 15:57:22 +0200 Subject: [PATCH 09/20] Documenting the branch names and branching strategy --- source/contribute/maintainer.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 2d5f35d6..ada4130c 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -128,13 +128,24 @@ nuances that are involved in the software development process. Branching Model --------------- -Merging topic branches: - -- 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. +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. Configuring Remotes ------------------- From d983267abed37bc693e6db530faef94d73998317 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 16:00:00 +0200 Subject: [PATCH 10/20] Documenting that automating the maintainer work should be one of the aims of maintainers and contributors --- source/contribute/maintainer.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index ada4130c..b78b121a 100644 --- a/source/contribute/maintainer.rst +++ b/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 ----- From a03e176e73bd7c524ba21cc1c98441bfdedd6596 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 16:07:40 +0200 Subject: [PATCH 11/20] Documenting the way in which release versions should behave --- source/contribute/maintainer.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index b78b121a..cf1c51cf 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -153,7 +153,19 @@ structure: * ``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. + 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. Configuring Remotes ------------------- From 85fb4154f0e7e3a546c323a45094d5ab9ae39c94 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 16:14:04 +0200 Subject: [PATCH 12/20] Example graph of the branching structure of a typical doctrine project --- source/contribute/maintainer.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index cf1c51cf..df7ef332 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -167,6 +167,19 @@ 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 + | \ + | ----- 1.1.1 ----- 1.1.2 ----- 1.1.x + \ + ----- 1.0.1 ----- 1.0.2 ----- 1.0.x + Configuring Remotes ------------------- From 272f9187e07e3d73e51778a34e1d896e6eb34166 Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 16:14:59 +0200 Subject: [PATCH 13/20] Adding `2.0.x` (mandatory release branch) attached to the `2.0.0` release --- source/contribute/maintainer.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index df7ef332..f9e038a5 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -175,6 +175,8 @@ git graph like following: ----- develop / 1.0.0 ----- 1.1.0 ----- 2.0.0 ------ master + | | \ + | | ----- 2.0.x | \ | ----- 1.1.1 ----- 1.1.2 ----- 1.1.x \ From be1d6d5fd46cdf202cf719f0ea98c2130833f94f Mon Sep 17 00:00:00 2001 From: Marco Pivetta Date: Wed, 29 Aug 2018 21:19:43 +0200 Subject: [PATCH 14/20] Documented release process --- source/contribute/maintainer.rst | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index f9e038a5..aaefabbf 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -182,6 +182,53 @@ git graph like following: \ ----- 1.0.1 ----- 1.0.2 ----- 1.0.x +Preparing a release +------------------- + +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 `_ + or `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 ------------------- From 268934ac0eec78880c616b16c13a6943f60af899 Mon Sep 17 00:00:00 2001 From: Claudio Zizza Date: Sun, 28 Oct 2018 23:38:24 +0100 Subject: [PATCH 15/20] Added deprecation policy link Co-Authored-By: Ocramius --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index aaefabbf..b9a6b356 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -100,7 +100,7 @@ is to sort incoming proposals by their category: 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" + API as "to be removed in future". Read about our `Deprecation Policy `_ - **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 From 21c97618be8cde735ebea4fe3464b2c950d4f4b0 Mon Sep 17 00:00:00 2001 From: Claudio Zizza Date: Sun, 28 Oct 2018 23:38:36 +0100 Subject: [PATCH 16/20] Added security policy link Co-Authored-By: Ocramius --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index b9a6b356..4da26435 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -98,7 +98,7 @@ is to sort incoming proposals by their category: - **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. + attack vectors. Read about our `Security Policy `_ - **deprecations** are changes to the codebase that do mark existing API as "to be removed in future". Read about our `Deprecation Policy `_ - **backwards-compatibility breakages** (or **BC breaks** in short) From 56078688a570e4e6c888d887d1956e2661cdb7ef Mon Sep 17 00:00:00 2001 From: Michael Moravec Date: Tue, 30 Oct 2018 10:28:58 +0100 Subject: [PATCH 17/20] Corrected capitalisation of `Doctrine` Co-Authored-By: Ocramius --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 4da26435..2e5ce6f6 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -139,7 +139,7 @@ Branching Model 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 +Packages in the Doctrine organisation should use the following branching structure: * ``develop`` - extremely unstable, points at the next planned From cd927784d210b36206a19e108605fe8cdb116789 Mon Sep 17 00:00:00 2001 From: Michael Moravec Date: Tue, 30 Oct 2018 10:29:14 +0100 Subject: [PATCH 18/20] Corrected capitalisation of `Doctrine` Co-Authored-By: Ocramius --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 2e5ce6f6..3937443c 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -167,7 +167,7 @@ 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 +This effectively means that a typical Doctrine package should have a git graph like following: .. code-block:: console From 221807b21a4c341822c598ae541186e687a0e9dc Mon Sep 17 00:00:00 2001 From: Michael Moravec Date: Tue, 30 Oct 2018 10:29:27 +0100 Subject: [PATCH 19/20] Corrected capitalisation of `Doctrine` Co-Authored-By: Ocramius --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 3937443c..37d40dcd 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -187,7 +187,7 @@ Preparing a release 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. +which for a Doctrine project also corresponds to a release. To do that: From 92a6365926838f4b81a4eed36ffb21d60b4bb980 Mon Sep 17 00:00:00 2001 From: Sebastiaan Stok Date: Mon, 4 Feb 2019 14:28:57 +0100 Subject: [PATCH 20/20] Replaced "assuming" with "given" to avoid iterpretation issues in the maintainer workflow Co-Authored-By: Ocramius --- source/contribute/maintainer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/maintainer.rst b/source/contribute/maintainer.rst index 37d40dcd..fd2749ac 100644 --- a/source/contribute/maintainer.rst +++ b/source/contribute/maintainer.rst @@ -185,7 +185,7 @@ git graph like following: Preparing a release ------------------- -Assuming that all tasks for a planned release are completed, a +Given that all tasks for a planned release are completed, a maintainer would then be in the position of preparing a git tag, which for a Doctrine project also corresponds to a release.