srl295/manual-land-icu-commit.md

## manual-land-icu-commit.md

      
    Raw
  

              manual-land-icu-commit.md
            
          
    Landing an ICU commit manually


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…
Prerequisite


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

Preparation

Online


Ensure CI builds are clean
check review status

Workspace

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 patches from the PR

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 the curl -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.


Verify

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

Test?


If in doubt, or At any step below, especially after a rebase, you can run ICU's tests locally.

Fix Commits

Rebase/Squash

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 to reword if you need to change the commit message.


To squash commits together, change lines from pick to squash. (You can't squash the first commit, leave that one as reword or pick.)


Save and quit the editor


Reword

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 commits

Eyeball check

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

Automated check

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.
Land it

Double check that no steps were skipped.. and you are ready to land this plane.
git push upstream master

Rejected push?

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.

Mark as closed

Close the PR with a message such as Landed in 95526ca301fa9951a6b4bcc04b52431d423ccdc4
Help, I'm stuck in a rebase!

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