Git and Github Usage

Using Git and GitHub in your Android team

At Freeletics we use Git and GitHub on a daily basis as vital tools for all our crucial projects. To help the entire engineering team contribute fast and effectively, we abide by a set of rules that we partly developed by ourselves, and partly imported from best practices in software development. Here are a few that you might find useful in co-ordinating your own workflow among your engineering team.

Branching

Main Branches

Naming Branches

A branch name should consist of the ticket number (if available) and a meaningful name. A dash should be used as a separator between words. Branch names should be lower case only.

Examples of good naming:

Prefixes

Some of the branches can contain prefixes like:

Those prefixes will trigger a release job on our CI server Jenkins, with each push to the branch.

Branch Owners

If you are the creator of a branch, you are also the owner. You are responsible for taking care of it over its entire lifetime. Responsibilities include:

Force-Pushing Branches

Credits

The whole system of Git branching is based on the widely used model of Vincent Driessen.

Commit Messages

  1. Use a short meaningful title (max. 80 characters)
  2. Use the description for detailed explanations
  3. Use International English
  4. Use present tense in imperative form (example: Add translations for Invite Friends screen).
  5. Use sentence case
  6. The ticket ID should be mentioned at the end of the description (separate line), not the title. Such meta data will work with the integration of the Bug Tracker system.
  7. Squash commits when it makes sense
  8. Commits should be atomic

Example of good commit message:

Add translations for Invite Friends screen

JIRA-713

Pull Requests

Pull Requests and code reviews should ideally be just a quick sanity check of your work. Remember this at all times and the process will be as hassle-free as it can get, for all developers that are involved. We use GitHub for reviewing Pull Requests, so some of the items belong to GitHub features and could be missing in other code review tools.

Why are we doing Pull Requests?

Rules

Before

Submission

Think of this before doing a Pull Request on develop: The feature or fix should be production-ready, so can be part of the next release.

Labels

In order to go through the list of Pull Request (PR), we have a different group of labels:

  1. Channel
    • beta – the PR should be merged to the current beta (next release) branch
    • hotfix – the PR should be merged as a hotfix to hotfix branch
  2. Status
    • wip (work in progress) - the PR is not ready to be reviewed in detail but the creator already wants feedback
    • ready – the PR is ready for review and can be picked up
    • blocked – the PR is blocked and cannot be reviewed at the moment
  3. Complexity. Defines the complexity of the PR in order to evaluate the PR faster
    • low
    • medium
    • high - If complexity is high, it alarms that probably something is wrong in the PR and creator should revise it.
  4. Team. Defines to which feature team the PR belongs. It helps to split visually PRs by different logical groups.
    • training
    • community
    • monetization
    • etc.

Keep the wip Pull Requests to a minimum, especially if they don’t at this stage need to be visible. This will give a better overview and saves the build power on Jenkins for PRs that actually need it. Remember that ideally you get your concept, architecture or class design challenged before you start implementing

Reviewing

Merging

Pull Request Templates

Pull Requests are inspected by different team members, allowing for an increasing amount of test criteria to be covered. The lists below create an important guide for developers to systematically test. For your daily work, stick to the Pull Request templates. Using a Strikethrough, cross out any items that might not be relevant for the specific Pull Request.

Example of the PR Template:

Description

To test

Definition of Done

Automation

All that’s mentioned above will always be supported by as much automation as possible. For instance, like using linters to reduce the amount of attention needed to focus on style violations all the time. We always challenge ourselves to see what else can be automated.

Resources

  1. https://github.com/thoughtbot/guides/tree/master/code-review
  2. http://kevinlondon.com/2015/05/05/code-review-best-practices.html
  3. http://blogs.atlassian.com/2010/03/code_review_in_agile_teams_part_ii/
  4. https://www.ibm.com/developerworks/rational/library/11-proven-practices-for-peer-review/
  5. http://nvie.com/posts/a-successful-git-branching-model/
  6. http://programmer.97things.oreilly.com/wiki/index.php/The_Boy_Scout_Rule