From 82bb2077ef824abe2828b2167e41fdcade161a44 Mon Sep 17 00:00:00 2001 From: Nathan Cutler Date: Wed, 4 Sep 2019 23:10:29 +0200 Subject: [PATCH] script/ceph-backport.sh: rewrite the documentation block Signed-off-by: Nathan Cutler --- src/script/ceph-backport.sh | 119 ++++++++++++++++++++++++------------ 1 file changed, 79 insertions(+), 40 deletions(-) diff --git a/src/script/ceph-backport.sh b/src/script/ceph-backport.sh index d3ccccbf87a..031d5080f91 100755 --- a/src/script/ceph-backport.sh +++ b/src/script/ceph-backport.sh @@ -4,25 +4,30 @@ # # Credits: This script is based on work done by Loic Dachary # -# With proper setup, this script takes care of opening the backport PR, -# updating the corresponding backport tracker issue, and cross-linking the -# backport PR with the tracker issue. +# With proper setup, this script automates the entire process of creating a +# backport -- all it needs is the number of the Backport tracker issue. +# Working in a local clone, the script creates a properly named wip branch for +# the backport, fetches the commits from GitHub, and cherry-picks them. If all +# the commits cherry-pick cleanly, the script goes on to open the backport PR, +# update the Backport tracker issue, and cross-linking the backport PR with the +# tracker issue. # -# However, before you start, some setup is required. Please be patient and -# read the "Setup instructions" and "Instructions for use" sections, below, -# carefully. If you still have issues, you could read the "Troubleshooting -# notes" section as well. +# Some setup is required for the script to work -- this is described +# in the "Setup instructions" and "Instructions for use" sections, below. +# If issues persist even after reading and following those instructions +# carefully, the "Troubleshooting notes" and "Reporting bugs" sections might +# come in handy, as well. # # # Setup instructions # ------------------ # # It is strongly suggested to copy the latest version of the script (from -# the "master" branch) into your PATH. In particular, do not use any version +# the "master" branch) into the PATH. In particular, do not use any version # of the script from a stable (named) branch such as "nautilus", as these # versions are not maintained. Only the version in master is maintained. # -# You will need to find the right values for the following: +# The script needs correct values for the following: # # redmine_key # "My account" -> "API access key" -> "Show" # redmine_user_id # "Logged in as foobar", click on foobar link, Redmine User ID @@ -31,56 +36,89 @@ # ensure it has "Full control of private repositories" scope # github_user # Your github username # -# Once you have the actual values for the above variables, create a file -# $HOME/bin/backport_common.sh with the following contents +# If one or more of these variables are not found in the environment, the +# script will attempt to source a file $HOME/bin/backport_common.sh. +# (Obviously, since that file might contain secrets, it should be protected from +# exposure using all available means - restricted file privileges, encrypted +# filesystem, etc.) # -# redmine_key=[your_redmine_key] -# redmine_user_id=[your_redmine_user_id] -# github_token=[your_github_personal_access_token] -# github_user=[your_github_username] +# The above variables must be set explicitly, as the script has no way of +# determining reasonable defaults. In addition, the following two variables +# should at least be checked against the output of "git remote -v" in your clone: # -# You can also optionally add yours and ceph remote repo's name in this file, -# like +# github_repo # The "git remote" name of your Ceph fork on GitHub; +# # defaults to "origin" if not set +# ceph_repo # The "git remote" name of the Ceph repo on GitHub; +# # defaults to "upstream" if not set # -# github_repo=[your_github_repo_name] -# ceph_repo=[ceph_github_repo_name] -# -# If you don't add it, it will default to "origin" and "upstream", respectively. -# -# Obviously, since this file contains secrets, you should protect it from -# exposure using all available means (restricted file privileges, encrypted -# filesystem, etc.). Without correct values for these four variables, this -# script will not work! +# Without correct values for all of the above variables, this script will not +# work! # # # Instructions for use # -------------------- # -# Assumes you have forked ceph/ceph.git, cloned your fork, and are running the -# script in the local clone! +# First, ensure that the latest version of this script (from +# src/script/ceph-backport.sh in the "master" branch of ceph/ceph.git) has been +# copied somewhere in your PATH. +# +# Second, change the working directory ("cd") to the top-level directory of the +# local clone. +# +# Third, choose a Backport tracker issue you would like to stage a backport for. +# Let's assume the Backport tracker issue you chose has the number 31459. +# +# Then run: +# +# ceph-backport.sh 31459 --prepare # -# With this script, backporting workflow for backport issue -# https://tracker.ceph.com/issues/19206 (a jewel backport) -# becomes something like this: +# Assuming 31459 is a properly-linked Backport issue and the "Pull request ID" +# field of the parent issue has been correctly populated, the script will +# automatically: # -# For simple backports you can just run: +# 1. determine which stable branch the backport is targeting +# 2. create a local wip branch based on the tip of that stable branch +# 3. cherry-pick the commits from the master PR # -# ceph-backport.sh 19206 --prepare -# ceph-backport.sh 19206 +# If there were no cherry-pick conflicts, the script will continue (see steps +# 4-6, below). # -# Alternatively, instead of running the script with --prepare you can prepare -# the backport manually: +# If any commit fails to cherry-pick cleanly, the script will abort, giving +# the user an opportunity to resolve the conflicts manually and re-run the +# script (without --prepare the second time) -- in that case the script will +# assume the current branch is the backport branch with cherry-picking +# completed, and start from step 4: +# +# 4. push the wip branch to the user's fork +# 5. open the backport PR on GitHub with the correct Milestone setting +# 6. properly cross-link the PR with the Backport tracker issue +# +# Finally, if a process called "firefox" is running, the script will open the +# PR and the updated tracker issue in that web browser to facilitate visual +# confirmation. +# +# Alternatively, instead of running the script with --prepare the user can +# prepare the backport manually. For a a luminous backport whose Backport +# tracker ID is 31459, the process would be: # # git remote add ceph http://github.com/ceph/ceph.git # git fetch ceph -# git checkout -b wip-19206-jewel ceph/jewel +# git checkout -b wip-31459-luminous ceph/jewel # git cherry-pick -x ... -# ceph-backport.sh 19206 +# (resolve conflicts if necessary) +# +# CAVEAT: the local branch name must be "wip-31459-luminous", where 31459 is +# the number of a Redmine issue in the Backport tracker, with Release set to +# luminous. The script will not work, otherwise. +# +# Finally, run the script: +# +# ceph-backport.sh 31459 # -# Optionally, you can set the component label that will be added to the PR with +# Optionally, the component label that will be added to the PR can be set with # an environment variable: # -# COMPONENT=dashboard ceph-backport.sh 40056 +# COMPONENT=dashboard ceph-backport.sh 31459 # # # Troubleshooting notes @@ -106,6 +144,7 @@ # -------------- # # Please report any bugs in this script to https://tracker.ceph.com/projects/ceph/issues/new +# Be sure to mention the exact version of git you are using. # # (Ideally, the bug report would include a typescript obtained while # reproducing the bug with the --debug option. To understand what is meant by -- 2.39.5