doc/dev/developer_guide: "What Is Merged and When?" could be less colloquial

Fixes: https://tracker.ceph.com/issues/46364
Signed-off-by: Anthony D'Atri <anthony.datri@gmail.com>

diff --git a/doc/dev/developer_guide/merging.rst b/doc/dev/developer_guide/merging.rst
index 6a8507bbc42f2d2c8368259e4f973e982b652fef..076e5b62a7e8913b9bdc22234e2c41404c681574 100644 (file)
--- a/doc/dev/developer_guide/merging.rst
+++ b/doc/dev/developer_guide/merging.rst
@@ -1,11 +1,10 @@
 .. _merging:
 
-What is Merged Where and When?
-===============================
+Commit merging:  scope and cadence
+==================================
 
-Commits are merged into branches according to criteria that change
-during the lifecycle of a Ceph release. This chapter is the inventory
-of what can be merged in which branch at a given point in time.
+Commits are merged into branches according to criteria specific to each phase
+of the Ceph release lifecycle. This chapter codifies these criteria.
 
 Development releases (i.e. x.0.z)
 ---------------------------------
@@ -13,38 +12,37 @@ Development releases (i.e. x.0.z)
 What ?
 ^^^^^^
 
-* features
-* bug fixes
+* Features
+* Bug fixes
 
 Where ?
 ^^^^^^^
 
-Features are merged to the master branch. Bug fixes should be merged
-to the corresponding named branch (e.g. "jewel" for 10.0.z, "kraken"
-for 11.0.z, etc.). However, this is not mandatory - bug fixes can be
-merged to the master branch as well, since the master branch is
-periodically merged to the named branch during the development
-releases phase. In either case, if the bugfix is important it can also
-be flagged for backport to one or more previous stable releases.
+Features are merged to the *master* branch. Bug fixes should be merged to the
+corresponding named branch (e.g. *nautilus* for 14.0.z, *pacific* for 16.0.z,
+etc.). However, this is not mandatory - bug fixes and documentation
+enhancements can be merged to the *master* branch as well, since the *master*
+branch is itself occasionally merged to the named branch during the development
+releases phase. In either case, if a bug fix is important it can also be
+flagged for backport to one or more previous stable releases.
 
 When ?
 ^^^^^^
 
-After the stable release candidates of the previous release enters
-phase 2 (see below).  For example: the "jewel" named branch was
-created when the infernalis release candidates entered phase 2. From
-this point on, master was no longer associated with infernalis. As
-soon as the named branch of the next stable release is created, master
-starts getting periodically merged into it.
+After each stable release, candidate branches for previous releases enter
+phase 2 (see below).  For example: the *jewel* named branch was created when
+the *infernalis* release candidates entered phase 2. From this point on,
+*master* was no longer associated with *infernalis*. After he named branch of
+the next stable release is created, *master* will be occasionally merged into
+it.
 
 Branch merges
 ^^^^^^^^^^^^^
 
-* The branch of the stable release is merged periodically into master.
-* The master branch is merged periodically into the branch of the
-  stable release.
-* The master is merged into the branch of the stable release
-  immediately after each development x.0.z release.
+* The latest stable release branch is merged periodically into master.
+* The master branch is merged periodically into the branch of the stable release.
+* The master is merged into the stable release branch
+  immediately after each development (x.0.z) release.
 
 Stable release candidates (i.e. x.1.z) phase 1
 ----------------------------------------------
@@ -52,18 +50,18 @@ Stable release candidates (i.e. x.1.z) phase 1
 What ?
 ^^^^^^
 
-* bug fixes only
+* Bug fixes only
 
 Where ?
 ^^^^^^^
 
-The branch of the stable release (e.g. "jewel" for 10.0.z, "kraken"
-for 11.0.z, etc.) or master.  Bug fixes should be merged to the named
-branch corresponding to the stable release candidate (e.g. "jewel" for
-10.1.z) or to master. During this phase, all commits to master will be
+The stable release branch (e.g. *jewel* for 10.0.z, *luminous*
+for 12.0.z, etc.) or *master*.  Bug fixes should be merged to the named
+branch corresponding to the stable release candidate (e.g. *jewel* for
+10.1.z) or to *master*. During this phase, all commits to *master* will be
 merged to the named branch, and vice versa. In other words, it makes
 no difference whether a commit is merged to the named branch or to
-master - it will make it into the next release candidate either way.
+*master* - it will make it into the next release candidate either way.
 
 When ?
 ^^^^^^
@@ -74,10 +72,9 @@ x.1.0 tag is set in the release branch.
 Branch merges
 ^^^^^^^^^^^^^
 
-* The branch of the stable release is merged periodically into master.
-* The master branch is merged periodically into the branch of the
-  stable release.
-* The master is merged into the branch of the stable release
+* The stable release branch is merged periodically into *master*.
+* The *master* branch is merged periodically into the stable release branch.
+* The *master* branch is merged into the stable release branch
   immediately after each x.1.z release candidate.
 
 Stable release candidates (i.e. x.1.z) phase 2
@@ -86,27 +83,26 @@ Stable release candidates (i.e. x.1.z) phase 2
 What ?
 ^^^^^^
 
-* bug fixes only
+* Bug fixes only
 
 Where ?
 ^^^^^^^
 
-The branch of the stable release (e.g. "jewel" for 10.0.z, "kraken"
-for 11.0.z, etc.). During this phase, all commits to the named branch
-will be merged into master. Cherry-picking to the named branch during
-release candidate phase 2 is done manually since the official
-backporting process only begins when the release is pronounced
-"stable".
+The stable release branch (e.g. *mimic* for 13.0.z, *octopus* for 15.0.z
+,etc.). During this phase, all commits to the named branch will be merged into
+*master*. Cherry-picking to the named branch during release candidate phase 2
+is performed manually since the official backporting process begins only when
+the release is pronounced "stable".
 
 When ?
 ^^^^^^
 
-After Sage Weil decides it is time for phase 2 to happen.
+After Sage Weil announces that it is time for phase 2 to happen.
 
 Branch merges
 ^^^^^^^^^^^^^
 
-* The branch of the stable release is merged periodically into master.
+* The stable release branch is occasionally merged into master.
 
 Stable releases (i.e. x.2.z)
 ----------------------------
@@ -114,21 +110,20 @@ Stable releases (i.e. x.2.z)
 What ?
 ^^^^^^
 
-* bug fixes
-* features are sometime accepted
-* commits should be cherry-picked from master when possible
-
-* commits that are not cherry-picked from master must be about a bug unique to
+* Bug fixes
+* Features are sometime accepted
+* Commits should be cherry-picked from *master* when possible
+* Commits that are not cherry-picked from *master* must pertain to a bug unique to
   the stable release
-* see also `the backport HOWTO`_
+* See also the `backport HOWTO`_ document
 
-.. _`the backport HOWTO`:
+.. _`backport HOWTO`:
   http://tracker.ceph.com/projects/ceph-releases/wiki/HOWTO#HOWTO
 
 Where ?
 ^^^^^^^
 
-The branch of the stable release (hammer for 0.94.x, infernalis for 9.2.x,
+The stable release branch (*hammer* for 0.94.x, *infernalis* for 9.2.x,
 etc.)
 
 When ?