- for ICU
- by Steven R. Loomis
- influenced by the procedure in Node's COLLABORATOR_GUIDE
You want to land a contribution to ICU. It's not by a team member. Given ICU's rebase-and-merge policy, the commits need to be formatted properly. You could ask the PR author to reformat their commits, and then use the Big Green Button. Otherwise, read on…
-
Note that we assume
upstream
is the master fork of ICU. -
Be sure the commit-checker is installed and functional.
cd tools/commit-checker
pipenv install
pipenv run python check.py --help
- (Note: this guide depends on steps not available in the commit-checker yet. See ICU-20233
- Ensure CI builds are clean
- check review status
Make sure you aren’t in the middle of anything (uncommitted files, etc.)
git status
Clear any am
/rebase
that may already be underway:
git am --abort
git rebase --abort
Checkout proper target branch:
git checkout master
Update your tree:
$ git fetch upstream
$ git merge --ff-only upstream/master
Apply external patches, cleaning up trailing whitespace. Replace 99999 with the PR #.
curl -L https://github.com/unicode-org/icu/pull/99999.patch | git am --whitespace=fix
If there is a merge conflict you can try one of these options:
-
OPTION A: Reset with
git am --abort
and then try a 3-way merge with thecurl -L https://github.com/unicode-org/icu/pull/99999.patch | git am --whitespace=fix -3
-
OPTION B: fix the merge yourself
-
OPTION C: contact the PR author and ask them to rebase.
At this point, verify the commit(s):
git log upstream..HEAD
Diff to see the actual contents, that they are as expected:
git diff upstream..HEAD
- If in doubt, or At any step below, especially after a rebase, you can run ICU's tests locally.
Here's where you can squash commits (if need be) and edit any commit messages. --autosquash
will attempt to squash any commits as requested by the author. (Note: I recommend a tool such as interactive-rebase-tool for the best git-rebase experience.)
git rebase -i upstream/master --autosquash
-
Change any lines from
pick
toreword
if you need to change the commit message. -
To squash commits together, change lines from
pick
tosquash
. (You can't squash the first commit, leave that one asreword
orpick
.) -
Save and quit the editor
Now you will get another editor for each commit you are editing.
- Make sure the 1st line has this form, where there's a space after the number:
ICU-00000
Some fix…
- Make sure the 2nd line is blank
- Break up long lines
Change the text to match conventions, and save and quit.
Check to see that the updated commits are as expected. Note that the original author's name is preserved, but the commit hash has changed.
git log --format=fuller upstream..HEAD
cd tools/commit-checker
pipenv run python check.py --rev-range upstream/master..master --jira-query=None --land
If the automated check fails, or you don't like the results, you can always run git rebase -i
again to reword
a commit.
Double check that no steps were skipped.. and you are ready to land this plane.
git push upstream master
If someone else landed a commit while you were doing all of this, you will get a rejected… fetch first
message from git.
- DO NOT RUN
git pull
HERE!!
If you run git pull
you will create a merge commit. And you really don't want to do that.
Instead:
- Run
git pull upstream master --rebase
to rebase your local master - Go back to Verify to check the state of your local master.
- You should then be able to push to master.
Close the PR with a message such as Landed in 95526ca301fa9951a6b4bcc04b52431d423ccdc4
I run some of these when I get stuck in a rebase. This will destroy any local work in your work tree, and get you back to a clean state.
git rebase --abort
git am --abort
git merge --abort
git checkout master
git fetch upstream
git stash
git reset --hard upstream/master