Git Workflow

Owned by Luka Mirosevic
Last updated: Mar 31, 2023 by Frank Hrom (Unlicensed)
6 min read

Status: Draft

Git Workflow

Preferred workflow

  • master or main is the mainline branch. Not develop.

  • Features are developed in feature branches. Keep them small and self-contained. If a feature takes a long time to develop, merge master back in regularly.

  • Features are merged into master after a finished code review.

  • Code in master should work, but there is no expectation that it's ready to release.

  • When code reaches release level quality, add a git tag (iOS/Android) or merge into the production branch (web/backend). See below.

Branches

Going forward please use this convention if you have ticket assigned:

  • feature/<jira-ticket-number>-<brief-description>: For new feature

  • bugfix/<jira-ticket-number>-<brief-description>: For bugfix

  • hotfix/<jira-ticket-number>-<brief-description>: For critical bug fixes that needs to be rolled out to production immediately

  • refactor/<jira-ticket-number>-<brief-description>: For refactoring existing codebase

  • chore/<jira-ticket-number>-<brief-description>: For tasks that are not in any of the above categories

We are trying to keep repositories organised, clutter-free and without long living branches so all branches should eventually get removed after getting merged to main branch. If you don't have ticket assigned which you should, try to be more descriptive then “small fixes“.

Example:

feature/JIRA123-add_splash_screen

refactor/remove_whitespaces_rename_variables

 

Commits

In theory commit should be atomic change, meaning that change should be able to be reverted and not cause conflicts in other parts of the system other than the one that is being reverted. We are trying to protect our main branch by not committing to it directly, only through pull request so we can have history in consistent and immutable state. If you have feature task at hand that is likely to be a big change, make new branch like above, try to break changes into smaller pieces (commits) and use commit message structured as below.

Message should be in two parts separated by blank line. Header, where you briefly explain what is done and link to Jira ticket if there is one, and if its more complicated so one-liner isn't enough, a body where you can go into more details why and how it's done.

When writing commit messages, please follow these guidelines to ensure consistency and clarity:

  • Use present tense verbs and imperative mood to describe what commit does (“Add splash screen“ instead of “Added splash screen“)

  • Keep header brief and to the point

 

Example:

Header Body

Add splash screen (jira-ticket-number) /n Explain in more details on how/what is done

Fix bug in settings screen (jira-ticket-number) /n Explain in more details on how/what is done

 

Pull requests

While commit can only contain one change, a PR can contain one or more changes that together form a high-level concern. As with commits we are also trying to make PR as atomic as possible. So if you have feature task assigned make PR only about that feature, leave things that are not feature related like whitespace changes, typo fixes, renaming to another PR, preferably before you even start developing feature task so if there will be need in the future to revert PR the likelihood of code conflict will be lower. Remember it's always easier to review 5 PR's with 200 changes each than 1 PR with 1000 changes.

When to do PR:

  • Whenever you want to directly commit to main branch

  • When you finished the task assigned to you

  • If you are working on bigger task, try to break down changes into smaller pieces and make PR for each piece

Ideally you would want to do reviewed pull requests often but in case its one man project and you don't have anyone to review it you are still encouraged to do it for consistency.

Please use this template for PR comment:

  • Description

    • What and why you did it

  • Changes

    • How you did it in more details, link to Jira tickets

  • Testing

    • How you tested it, relevant logs, error messages

  • Screenshoots

    • If UI related changes you can add some screenshots

  • Additional Info

    • Additional information for reviewer(yourself)

Example:

## Description Added support for tire scan mode ## Changes Added new scan mode configuration file, added new scan mode to OCR Fragment and handle result for new scan mode in Result Fragment. See JIRA-123, JIRA-124 for more information. ## Testing Tested manualy on Samsung S10, Huawei P30 with client provided examples. LGTM ## Screenshots Pictures or links ## Additional Info Let's consider refactoring RecorderFragment in the future to make it more modular. Each new mode added is getting harder and to implement.

 

Code Review

Some of general practices for reviewing code:

  • Quality comes before quantity, limit yourself to review up to 300 lines of code at once

  • Don't spend more then one hour at a time reviewing because your review will become less effective and attentive

  • Provide constructive feedback (not only “This is wrong, why did you do this?“)

  • If you suggest an alternative explain why to teach original author, also reduces the need to follow-up with questions for context

  • Use code review checklist that can contain:

    • Readability: Is it clear what the code is doing?

    • Performance: Is it slow to run? Is there a simpler/quicker solution?

    • Reusability and maintainability: Does the code follow SOLID practices?

    • Test coverage: Any edge cases?

  • Focus on 9y coding standards, not personal preference

Code reviews are opportunity to improve codebase maintainability but also to discuss, share knowledge and mentorship. Even experienced developers can sometimes learn from beginners.

 

Release Management

Versioning:

  1. Major Version - X.0.0:

  • The major version number should be incremented when there are major changes to the software that are not backward compatible. For example, a major version change might be warranted if you’ve completely rewritten the software, added or removed major features, or made significant changes to the software’s architecture.

2. Minor Version - 0.X.0:

  • The minor version number should be incremented when new features or functionality are added to the software in a backward-compatible manner. For example, if you’ve added a new feature or improved an existing feature, you might increment the minor version number.

3. Patch Version - 0.0.X:

  • The patch version number should be incremented when bugfixes or minor changes are made to the software. For example, if you’ve fixed a bug or made a small change to the user interface, you might increment the patch version number.

Release Branches:

When preparing to release a new version of the software, you should create a release branch from the develop branch. The release branch should only contain bugfixes and minor changes that are required for the release. Release branches should be named using a convention that reflects the version of the software that is being released. For example, if you are releasing version 1.2.3 of the software, you might create a release branch named release-1.2.3. Once the release branch is created, it should be thoroughly tested to ensure that it contains all the necessary bugfixes and changes required for the release. Once the release is complete, the release branch should be merged into the main branch.

Tagging:

Once the release branch has been merged into the main branch, you should create a tag for the release. This tag should be named with the version number of the release, and should be pushed to the remote repository.

 

Automated CI/CD

Mobile:

  • CI will automatically pick up changes on master and distribute builds to project stakeholders

  • (optional) tagging a commit with release/1.2.3/1 will trigger a production deploy of the application. 1.2.3 is the version, 1 is the release candidate number

Web/Backend

  • CI will automatically pick up changes on master and deploy to the staging environment

  • (optional) merging master into production branch will trigger a deployment to production infrastructure

  • Hotfixes can be done directly off the production branch. These should then be cherry-picked onto the master branch immediately.

 

Email address for commits

Use your @9y.co email address for commit messages.

On a single repository:

git config user.email "me@9y.co"

Globally:

git config --global user.email "me@9y.co"

See https://help.github.com/en/articles/setting-your-commit-email-address-in-git for further info.

 

Readme.md

Readme file is the first impression the new developer on a projects gets. Let’s try to make it simple and to the point and hopefully it should give more answers than questions to the new guy.

Generally the purpose of readme file is to answer these questions:

  • What is project trying to achieve? Short description.

    • It would be great if project description can be summarised in few sentences.

  • What are prerequisites? Platform, stack…

    • User can quickly see if he can run it

  • How to install it? Describe installation process, CLI commands

Here is repository with Readme.md as template that you can use on your projects.

 

P.S.


These rules are not set in stone, they are more of a guidance than a law since we can't have rules for every possible situation that could arise. If something makes more sense, or something here doesn't, you can always consult with someone or do it the way you think it should be done.

Ideally, we want someone new to the project be able to browse trough the whole source and history of commits without having to talk to original author(he might not be available, can't remember anymore). If commit does one thing and if PR does one thing in the future we can have better understanding of why those lines in codebase were changed.

 

Owner

Reviewer