# Flashboys Git

## Introduction

**Flashboys Git** guidelines describes basic usage, best practices and code flow for any Flashboys project based on Git SCM.

**Flashboys Git MD** will cover things as naming conventions, code merging, conflict resolving and command use cases.

## General

For external & internal projects, Flashboys use Azure DevOps Git SCM with Azure build & release pipelines.

Projects should have the following branch spec:

- **dev** - main development branch, features, fixes, experimental stuff, all go eventually into this branch
- **master** - project version branch and pre-production (staging) code, acts like a version history of the project (release branches merge into this one)

Project should have the following CI/CD spec:

- **development** - builds **dev** and publishes to the development environment (url pattern: *{app-name}-dev.{cloud-domain}*)

- **staging** - builds **master** and publishes to the staging environment (url pattern: *{app-name}-staging.{cloud-domain}*)

- **PR builds** - builds **feature/*** branches while undergoing review process (not necessary if build agent pool is limited)

------
*cloud-domain - refers to the cloud provider default domain (azurewebsites.net, herokuapp.com, etc.)

## Naming

### Branches

1. Branches should be prefixed regarding the problem they solve or feature they bring by merging them into **dev**:

- **feature** - new stuff that hasn't been seen and bring new value to the project
- **hotfix** - urgent code fixes that need immediate attention and asap merging
- **fix** - code fixes that aren't urgent for solving, but aren't long-term as the next candidate
- **refactor** - code refactoring, stabilization, pattern introduction, enhancements and additional code quality improvements
- **experimental** - branches that have short a lifetime, include some tests and eventual code improvements using new libs and researches
- **release** - version releases on **staging** environment; PRs target **master** branch
- **/public_vX.Y.Z** - public releases which artifacts are visible and usable by customers and end-users
- **/internal_vX.Y.Z** - internal releases for demos, reviews and showoffs for teams or internal clients
X - major version (only when the system has a breaking change like migrating to a higher version)
Y - minor version (number of new features in the version)
Z - patch number (number of fixes applied in the version)

2. Branch names should encapsulate the complete effect that will take place if merged into another branch. The naming should be short, concise and contained in 1-5 words.

Good examples :+1: :

- *feature/payment-modal*
- *refactor/db-layer*
- *hotfix/segment-ecommerce-event-duplication*
- *release/public_v2.14.0*
- etc.

Bad examples :-1: :

- *feature/modal-conflict* (obviously two modals conflicting isn't a *feature*)
- *hotfix/bug* - (ofc it's a bug, more specific)
- *refactor/minor-changes-auth0-service-user-patching* - not clear what's been refactored and too many words

### Commits

Commits should contain few lines of code that encapsulate one unit of work (like chaning one button, fixing one endpoint, adding a new method in the service).

Regarding commit messages the rules are following:
- keep messages short, but containing the whole work
- write in imperative (have this sentence in mind: `If this commit is applied it will {your commit message}`)
- if a commit needs more text, keep the first line short and add break lines (shift + enter) which add additional text to messages

Good examples :+1: :
- *Fix modal on Buy page*
- *Enable token soft cap*
- *Improve token info*

*Add token symbol*
*Add activness indicator*
*Remove unnecessary amount fields*

Bad examples :-1: :
- *Fixed green button*
- *Change behaviour of login button when clicked on it*
- *Fix* or *Refactor*

### Release

Release PR messages need to comply with the following format:

Description:

**Fixes**:
- Fixed A
- Fixed B
...

**Features**:
- Added component
...

**Notes**:
- New app setting added
- New db string added
...

## Conflicts

When `>=2` developers work on the same component, package, file or class, in a tight time range, conflicts can emerge, due to Git's merging strategies and too much correlation between the edited files.

When those events show up (mostly on PRs or when pulling an updated branch into a locally update branch), we use `Visual Studio Community` or `Visual Studio Code` merging tools.

These tools open up the remote and local file and give the developer the ability to merge manually all conflicts. **NOTE**: _the best way to avoid code deletion or missing code at the end, contact the person who was on these lines and merge the files together_.

## Flow

Code is being merged via Pull Requests. Branches **dev** and **master** are ,by default, locked and pushing directly is denied.

After the know what tools we use, how we name things and resolve conflicts, let's see how the coding flow goes:

1. `git checkout dev` - checkout on **dev** branch
2. `git pull dev` - pull latest changes
3. `git checkout -b {name}` - create a new branch based on **dev**
4. code, test, finetune, benchmark, get some :coffee:, eat :pizza:
5. `git checkout dev && git pull` - checkout on **dev** and retrieve the latest updates (if someone is also developing actively on the same project, new code could be on **dev** which you don't have locally)
5*. `git rebase dev` - rebase onto **dev**, in case there were some new changes
6. `git push -u origin {name}` - push the branch on the remote
7. create a PR targeting **dev** branch

**NOTE**: before completing your PR be sure to tick the **delete branch after merge** and **squash commits** boxes (if the options are present).

## Notes

Any improvement on the current flow is highly welcome. Bear in mind that Git is a powerful tool, but only when used in the right way.

> With great power comes great responsibility.
> --- Uncle Ben from Spiderman