Common Git Workflow with Gerrit
Suggested Git Workflow
(Helps avoid common Code Review issues)
One of the most common issues we run into with the Code Review tool, is when we aren’t able to submit a successful Code Review result into the main code stream (repository, branch, origin/master, etc…) due to outdated or funky dependencies of the Code Review. (dependencies are the commit(s) which are the predecessors of a given commit, i.e. which commits a given commit is based on. Merges have two predecessors and normal commits only have one)
The purpose of this section is to suggest a workflow that will help avoid common pitfalls that cause these issues to occur.
To get a feel for how the Code Review system works you can see a diagram and explanation here.
NEVER make a commit to your local master branch
NEVER make a commit to your local master branch. Instead you will ALWAYS create a new local branch before you start working or making changes. (I suggest using the JIRA ID of the issue you are working on as the branch name i.e. LDSMUSIC-320, although this is not crucial; you can use whatever name you desire)
This helps to keep your local master branch in sync with the main code stream (origin/master), which allows you to always be able to switch back to the main code stream at any time.
ALWAYS make your changes on a local branch
ALWAYS make your changes on a local branch. Feel free to make as many commits on this local branch as you see fit to keep things organized, HOWEVER, when you are ready to submit the changes for code review, you MUST squash all your new commits into one. (And make sure the resulting commit message only contains a single change-id)
Here is what will happen if you make multiple commits on your local branch and push for code review without squashing them into one commit. When you push these commits you will create Multiple Code Reviews (one for each commit). If any of the first commits do not pass review for any reason you will need to submit a new Patch Set for it, this is where the problems begin. This new Patch Set will have a different commit hash ID, but the same code review ID. Having a different commit hash ID causes the newer commits that had the original Hash ID as their predecessor to now have OUTDATED dependencies. Depending on the nature of the OUTDATED dependencies they can be fairly easy, or to resolve (without painful manual intervention).
Once your Code Review gets successfully submitted into the main code stream (origin/master) you can grab those changes locally by pulling from origin/master into your local master. Since you never make commits to your local master branch this operation will always be a fast-forward and won’t require any fancy merging.
ALWAYS pull new code from the main code stream (origin/master) into your local master, NEVER merge code from your local branches back into your local master branch
ALWAYS pull new code from the main code stream (origin/master) into your local master (including changes that you made and submitted through Code Review),NEVER merge code from your local branches back into your local master branch.
There is no guarantee that your actual commit (with its associated hash ID) will be the one that gets submitted into the main code stream (origin/mater). The people in charge of making this final submission may need to rebase or merge your commit to get it to submit properly (which will change its commit hash ID). If you start on a new feature based on the older commit hash ID that wasn’t submitted to the main code stream your next feature will be difficult to integrate. Following this suggestion helps keep your local master branch in sync with origin/master and therefore helps make new features you develop (which will be made on branches that were based of your master branch) be easily integrated.