------------------
To help the people who will review your backport, please state either in the
-backport PR, or in the backport tracker issue, or in the master tracker issue:
+backport PR, or in the backport tracker issue, or in the ``main`` branch tracker issue:
1. what bug is fixed
2. why this fix is the minimal way to do it
The following rules, which have been codified from "best practices" developed
over years of backporting, apply to the actual backport implementation:
-* all fixes should land in master first
-* commits to stable branches should be cherry-picked from master
-* before starting to cherry-pick a set of commits from master, grep the master git history for the SHA1 of each master commit (using ``git log --grep``) to check for follow-up fixes. Include any follow-up fixes found in the set of commits to be cherry-picked.
-* when backporting a master PR to a stable branch, double-check that the backport PR contains cherry-picks of all of the master PR's commits. If any commit needs to be omitted, declare and explain this in the PR.
+* all fixes should land in ``main`` first
+* commits to stable branches should be cherry-picked from ``main``
+* before starting to cherry-pick a set of commits from ``main``, grep the ``main`` git history for the SHA1 of each ``main`` commit (using ``git log --grep``) to check for follow-up fixes. Include any follow-up fixes found in the set of commits to be cherry-picked.
+* when backporting a ``main`` PR to a stable branch, double-check that the backport PR contains cherry-picks of all of the ``main`` PR's commits. If any commit needs to be omitted, declare and explain this in the PR.
* cherry-picks must be done using ``git cherry-pick -x``
-* if a cherry-pick from master is not feasible and a direct fix is being undertaken, this must be explained
+* if a cherry-pick from ``main`` is not feasible and a direct fix is being undertaken, this must be explained
* the commit message generated by ``git cherry-pick -x`` must not be modified, except to add a "Conflicts" section below the "cherry picked from commit ..." line added by git
* the "Conflicts" section must mention all files where changes had to be made manually (not just conflicts flagged by git)
* the "Conflicts" section should also describe the manual changes that were made
Notes on the cherry-picking rules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-What does "all fixes should land in master first" mean? What if I just need to
+What does "all fixes should land in ``main`` first" mean? What if I just need to
fix the issue in <release>?
As the person fixing the issue, you are required to first check whether the
-issue exists in master. If it does, then the proper course of action is to
-create a master tracker (see `Tracker workflow`_) and fix the issue in master,
+issue exists in ``main``. If it does, then the proper course of action is to
+create a ``main`` branch tracker (see `Tracker workflow`_) and fix the issue in ``main``,
first, and only then cherry-pick the fix to the stable branches that have the
issue.
-If the issue exists in the stable branch, but not in master, there are several
+If the issue exists in the stable branch, but not in ``main``, there are several
possibilities:
1. it's a regression introduced into the stable branch by a bad backport
-2. the issue was fixed in master by some massive refactoring that cannot be backported
-3. the issue was already fixed in master by a cherry-pickable commit
+2. the issue was fixed in ``main`` by some massive refactoring that cannot be backported
+3. the issue was already fixed in ``main`` by a cherry-pickable commit
In cases 1 and 2, it's permissible to fix the issue directly in the most recent
stable branch, subject to the rule "if a commit could not be cherry-picked from
-master, the commit message must explain why that was not possible". Once the
+``main``, the commit message must explain why that was not possible". Once the
fix has landed in the most recent stable branch, it can be cherry-picked to
older stable branches from there.
Any change that is to be backported to multiple stable branches should have
an associated tracker issue at https://tracker.ceph.com.
-For fixes already merged to master, this may have already been done - see the
-``Fixes:`` line in the master PR. If the master PR has already been merged and
-there is no associated master tracker issue, you can create a master tracker
+For fixes already merged to ``main``, this may have already been done - see the
+``Fixes:`` line in the ``main`` PR. If the ``main`` PR has already been merged and
+there is no associated ``main`` branch tracker issue, you can create a ``main`` branch tracker
issue and fill in the fields as described below.
-This master tracker issue should be in the "Bug" or "Feature"
+This ``main`` branch tracker issue should be in the "Bug" or "Feature"
trackers of the relevant subproject under the "Ceph" parent project (or
in the "Ceph" project itself if none of the subprojects are a good fit).
-The stable branches to which the master changes are to be cherry-picked should
+The stable branches to which the ``main`` changes are to be cherry-picked should
be listed in the "Backport" field. For example::
Backport: mimic, nautilus
-Once the PR targeting master is open, add the PR number assigned by GitHub to
+Once the PR targeting ``main`` is open, add the PR number assigned by GitHub to
the tracker issue. For example, if the PR number is 99999::
Pull request ID: 99999
-Once the master PR has been merged, after checking that the change really needs
-to be backported and the Backport field has been populated, change the master
-tracker issue's ``Status`` field to "Pending Backport".
+Once the ``main`` PR has been merged, after checking that the change really needs
+to be backported and the Backport field has been populated, change the ``main``
+branch tracker issue's ``Status`` field to "Pending Backport".
Status: Pending Backport
--------------------------------
To track backporting efforts, "backport tracker issues" can be created from
-a parent "master tracker issue". The master tracker issue is described in the
+a parent "``main`` branch tracker issue". The ``main`` branch tracker issue is described in the
previous section, `Tracker workflow`_. This section focuses the backport tracker
issue.
-Once the entire `Tracker workflow`_ has been completed for the master issue,
-issues can be created in the Backport tracker for tracking the backporting work.
+Once the entire `Tracker workflow`_ has been completed for the ``main`` branch tracker issue,
+issues can be created in the backport tracker issue for tracking the backporting work.
-Under ordinary circumstances, the developer who merges the master PR will flag
-the master tracker issue for backport by changing the Status to "Pending
+Under ordinary circumstances, the developer who merges the ``main`` PR will flag
+the ``main`` branch tracker issue for backport by changing the Status to "Pending
Backport", and volunteers from the `Stable Releases and Backports team`_
periodically create backport tracker issues by running the
``backport-create-issue`` script. They also do the actual backporting. But that
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The script used to create backport issues is located at
-``src/script/backport-create-issue`` in the master branch. Though there might be
+``src/script/backport-create-issue`` in the ``main`` branch. Though there might be
an older version of this script in a stable branch, do not use it. Only use the
-most recent version from master.
+most recent version from ``main``.
Once you have the script somewhere in your PATH, you can proceed to install the
dependencies.
tedious if you do it more than once in a long while.
The ``ceph-backport.sh`` script automates the entire process of cherry-picking
-the commits from the master PR, opening the GitHub backport PR, and
+the commits from the ``main`` PR, opening the GitHub backport PR, and
cross-linking the GitHub backport PR with the correct Backport tracker issue.
The script can also be used to good effect if you have already manually prepared
the backport branch with the cherry-picks in it.
-The script is located at ``src/script/ceph-backport.sh`` in the ``master``
+The script is located at ``src/script/ceph-backport.sh`` in the ``main``
branch. Though there might be an older version of this script in a stable
-branch, do not use it. Only use the most recent version from the master branch.
+branch, do not use it. Only use the most recent version from the ``main`` branch.
To do this from anywhere and from any branch use the following
-alias that will use the most recent script in ``upstream/master`` of your
+alias that will use the most recent script in ``upstream/main`` of your
local ceph clone on every call::
- alias ceph-backport="bash <(git --git-dir=$pathToCephClone/.git --no-pager show upstream/master:src/script/ceph-backport.sh)"
+ alias ceph-backport.sh="bash <(git --git-dir=$pathToCephClone/.git --no-pager show upstream/main:src/script/ceph-backport.sh)"
``ceph-backport.sh`` is just a bash script, so the only dependency is ``bash``
itself, but it does need to be run in the top level of a local clone of
src/osd/batlo.cc
- add_batlo_check has an extra arg in newer code
-Naturally, the ``Fixes`` line points to the master issue. You might be tempted
+Naturally, the ``Fixes`` line points to the ``main`` issue. You might be tempted
to modify it so it points to the backport issue, but - please - don't do that.
-First, the master issue points to all the backport issues, and second, *any*
+First, the ``main`` issue points to all the backport issues, and second, *any*
editing of the original commit message calls the entire backport into doubt,
simply because there is no good reason for such editing.
a script (``ceph-backport.sh --milestones``) which scans all PRs targetting stable
branches and automatically adds the correct Milestone tag if it is missing.
-Next, check which component label was applied to the master PR corresponding to
+Next, check which component label was applied to the ``main`` PR corresponding to
this backport, and double-check that that label is applied to the backport PR as
-well. For example, if the master PR carries the component label "core", the
+well. For example, if the ``main`` PR carries the component label "core", the
backport PR should also get that label.
In general, it is the responsibility of the `Stable Releases and Backports
Ceph has a `Stable Releases and Backports`_ team, staffed by volunteers,
which is charged with maintaining the stable releases and backporting bugfixes
-from the master branch to them. (That team maintains a wiki, accessible by
+from the ``main`` branch to them. (That team maintains a wiki, accessible by
clicking the `Stable Releases and Backports`_ link, which describes various
workflows in the backporting lifecycle.)
projects / ceph.git / blobdiff