From: Anthony D'Atri Date: Tue, 17 Nov 2020 23:40:10 +0000 (-0800) Subject: doc/dev/developer_guide: "What Is Merged and When?" could be less colloquial X-Git-Tag: v16.1.0~483^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F38143%2Fhead;p=ceph.git 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 --- diff --git a/doc/dev/developer_guide/merging.rst b/doc/dev/developer_guide/merging.rst index 6a8507bbc42f..076e5b62a7e8 100644 --- 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 ?