Descendant dating app walkthrough

We have successfully adopted the Gerrit workflow for pre-commit code review in Evojam. We believe that this a foundation of high quality of our solutions. After two years we have worked out a complete approach for the pre-commit review with Gerrit, branching model and application provisioning. Now I have realized the there is no definite cookbook for the newcomers. This led me to the idea that it may be worth to share this approach with the community. This is not totally unique but may save a newcomer a bit of time.

Preface

This guide is extremely detailed. It is aimed at people doing their Gerrit workflow setup right now. If you are already familiar with Gerrit you may jump directly to the workflow description. While writing I took few assumptions about environment you work on:

• Gerrit is already installed and configured.
• You have CI, eg.: Jenkins installed and configured, builds are triggered automatically to verify the code
• You have credentials and privileges in Gerrit
• The test environment reflects the state of the development branch and is deployed automatically
• The staging environment is updated manually to Release Candidate versions, tagged on the release branch
• The Gerrit instance is a central GIT repository
• The production environment is updated manually from promoted RC builds.

I assume you are familiar with GIT terminology and that you have access to a terminal with git tools ready to use. If you need additional introduction I suggest starting with http://git-scm.com/docs/gittutorial.

In all examples I have used my login . Please, replace it with yours. For the sake of clarity of the examples I assume that Gerrit is available under https://gerrit.example.com, remember to use your custom domain in urls.

Branching model

Our basic branching model includes only two branches. In rare cases it is acceptable to add feature branches in the central repository, I have described this below in details.

master

The branch holds the current development code. All changes made by developers, except from hotfixes are prepared upon the HEAD of the branch. The code in branch is updated via requests. Change requests are merged manually when both conditions are met:

1. Change receives positive Code Review done by team members.
2. Code Validation done by Jenkins finishes successfuly.

release

The branch is maintained to trace production ready code. Code from branch is merged to branch once ready to release as a candidate. Usually it can be done with fast-forward strategy.

feature branches

Feature branches are discouraged due to the additional complexity of merging two totally diverged branches. It may be beneficial to create additional feature branch only in special cases. For example when the enormous feature complexity might risk that the development process will take longer than few weeks. In such case a feature branch is going to replace the current master. You may also have a requirement to maintain legacy version of the shared library code and keep the old branch as is.

The feature branch has to be manually created in Gerrit. To do this, user must have appropriate privileges assigned.

The feature branches are subject to all restriction that are applied to ordinary branch. The development workflow is exactly the same.

Creating feature branch

Open Gerrit in your favorite web browser and navigate to the project management page through tabs. Open the tab. Here you can create new feature branch from the .

Development

Depending if you do a fresh start or have the code already you may want to skip to part A. or B. below.

A. For a fresh start

SSH keys

If you have never interacted with Gerrit you have to add your public ssh key in User Settings. You can find the link to the page when you click on your name in the top right corner of the Gerrit page. If you are not familiar with SSH keys you may be interested in the first two steps from GitHub SSH manual.

Identity

Your identity description in the has to match your account configuration in Gerrit. My section uses my Gmail account, thus I had to update my user settings in Gerrit.

Git Aliases

You don't have to add any aliases in your but I recommend you try the following:

Some aliases, like and are just git shorthands I use to make my everyday work more enjoyable.

Cloning

To start working on the code you have to get the copy of the repository to your local computer. Open Gerrit and navigate to the page. In the tab you can find ready-to-use git command. You can either use pure or . Second includes the call which copies the Gerrit hook into your local repository hooks directory. Please, execute the second version. You will get something similar to the example below:

What you will get is an ordinary clone of the remote repository in a subdirectory. To start the real work you need a local development branch.

B. When You Already Do Have The Copy

Always pull the current state of the branch from the central repository before you are about to create new local branch. This will allow you to avoid unnecessary code conflicts and rebases. Usually you will be branching from so for example it will look like this:

Local Branching

Local branches are never directly pushed to the so feel free to use the name you like. I suggest the abbreviated ticket subject, eg: filter-aggregation for the task Filters should aggregate data. We have pulled the current branch state from the and switched to the .

Now with the local branch you can start the real coding part.

The Change

In the Gerrit world the code in the branch on central repository is highly protected. Every time you are about to push some commit into Gerrit you will be preparing a Change. Each commit you push locally to your branch will become a separate Change in Gerrit and will live its own life.

Pushing the Change to Gerrit

Once the code is ready, please verify that it passes all the tests. If you skip this step Jenkins will forbid us to merge the change into target branch.

If you forgot about gerrit hook, Gerrit will let you know with the very unequivocal message and a hint how to fix it. You will be asked to execute something like this:

Prepare ordinary commit in your local branch. We tend to keep up with the good practice of subject formatting, thus name it by following this convention:

• Make it concise, keep the length below 100 characters.
• Use present simple.
• Remember about the ticket number eg.: .
• If the commit is huge, which is discouraged, add the broader info in the description.

If you have properly copied the Git hook, the commit message will look like this:

Do not remove Change-Id unless you have strong confidence how it will affect the Gerrit behavior. Now it's time to push the code to Gerrit. Instead of ordinary you use an alias . The result will be similar to the example:

Congratulations, you have published your change with the patchset number 1. Each Change in Gerrit includes at least one Patchset which represents a single successful .

Code Validation

Once the commit is pushed to Gerrit as a Change the fully automated code validation process starts. Depending on the build definition, Jenkins runs set of lint checks and tests (please, follow the description for the specific project).

Jenkins will run the tests and rate the change with either or score. If the score is we can proceed with peer Code Review. Otherwise either compilation or tests have failed and you have to fix them. You will find the cause in the build output which is in the log of the Jenkins job. The url is posted automatically by Jenkins in the change history.

Code Review

The code review is done by your teammates. You should never score your own change. In the review process you can either get:

• when the reviewer is certain of some flaws in the change that are not easily fixable and he would like to check the code when you push the fixes
• when the reviewers found some minor issues in your change but it can be easily fixed
• when the code is good but he's not confident enough to merge
• when the code is good enough to merge.

Along with the score you may receive comments for the files included in the change. I encourage you to reply to them, either with simple or with arguments that will make the reviewers change their decision. Remember that comments are in draft until you publish them with button available in the change summary.

When you know you have accidentally pushed the change that should not be reviewed you may score your change with score. It will prevent other developers from reading it, until you fix it and remove the score.

The Success

When the change has no less than score in total from your reviewers and at least one person gave it may be . It does not happen automatically, there is a button for this and traditionally it is done by the last reviewer who gives the positive score. Gerrit will forbid you to merge the commit when the score restriction is not met.

After the merge your commit shows up in the branch the change was pushed to. If it is the branch Jenkins runs the build and pushes the changed code to the test environment automatically and restarts the applications if necessary. After few minutes you can test the change integrated with the .

What if it's not good enough

Either you got from Jenkins or from your teammates or the code cannot be fast forwarded automatically by Gerrit you will have to take an action yourself.

Fixing

1. Update the code, commit message according to the comments you have received. You may try to do this via the Gerrit inline editing but it's often easier and quicker to make it locally.
2. When you are done, use to update your change. This way, the git history will be clean, the rest will be done by Gerrit. Do not add a separate commit.
3. Use as you did previously. Your change in Gerrit will get updated with new patchest.

Rebasing

Sometimes, it happens that while you were coding, the target branch (in most cases ) has diverged from the state where you started. To merge the change the rebase is required. Let's assume you have been pushing to .

1. Go to the branch locally and pull from Gerrit, which is usually an remote.
2. Switch your local branch and use . You will be able to resolve conflicts.
3. When you are done use and after successful end up with the commit on top of the current branch.
4. Use as you did previously to update the change in Gerrit and publish new patchest.

Releasing an RC to staging

To release an RC you have to merge current to the branch.

Merge to release branch

Pull the and branches from Gerrit so you can prepare merege. Switch to branch and use command. Don't use fast forward as you need a explicit merge commit to produce new change identifier (the switch). This way the branch history is much cleaner for us when the time passes. Remember to change default commit title to something related to the release content. See example below.