Skip to content

Git Guideline

This procedure explains how we use Git on our repositories.

Development Strategy

The punchplatform team follows a trunk base development process. The most important observation is the following:

Quote

Branches create distance between developers and we do not want that

In a nutshell, there is a single branch. We commit often, we do not stop coding whenever a release approaches, the single branch is always release ready, and all developers run the build locally.

Make sure you read the trunk based developments observed habits.

Guideline

Git Setup and Tips

Pull with rebase

By default, the command git pull is equivalent to git fetch + git merge. This introduces unnecessary commit messages that look like this one:

1
2
3
4
5
6
commit 715656890ed6956ff19a1475460a757383f35e96
Merge: 841b12d c80e510
Author: [...]
Date:   Thu Dec 6 17:07:52 2018 +0100

    Merge branch 'craig-stable' of 'origin/craig-stable'

This puts some useless commits that mess up the history log readability. To avoid them, use the following flag whenever your pull. It will place your local work on top of the distant branch state.

1
$ git pull --rebase origin craig-stable

Tip

To never forget the --rebase flag (and save some extra time) at each Git pull, set it in your global Git configuration with: git config --global pull.rebase true

Deal with previous local commit

The following sequence is very frequent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
cd pp-core

# I edit something 
vim README.md 
git add README.md
git commit -m "PP-XXXX update prerequises in pp-core"

# Oops, I forgot something, I re-edit...
vim README.md
git add README.md

# And now ?? how to re-commit this last change ?

The following is bad:

1
2
# BAD solution: Create a new commit with same message.
git commit -m "PP-XXXX update prerequises in pp-core"

This too:

1
2
# BAD solution: Create an other commit with other message.
git commit -m "PP-XXXX fix update prerequises in pp-core"

Do this so that you end up with a clear history of a single commit:

1
2
# GOOD solution: Append changes to previous commit !
git commit --amend 

Amen --amend

You can use git commit --amend when you want to edit your last commit message !

Advanced: Manage your local commits

To learn more about how you can manage you local commits to keep a clearer Git history, see Git-Tools-Rewriting-History.
WARN: use it with caution !

Use short lived branches

Make sure you understand our trunk-based development strategy. Always work in short-lived local branches. Save them regularly on the remote repository.

It can happen, of course, you work on a more ambitious revamp or task that require a longer lived branch, but at the end, all branches are meant to quickly disappear and your work fll back to the unique production ready branch.

Do not forget

what you commit is scrutinized by all of us, we all depend on each others. Nobody else than you will have to test your development

Write useful commit message

When you merge your branch into a shared branch craig-stable, write clear, complete, and useful commit messages. These will appear in release notes and be used by all of us to understand what is going on.

Stable, stable and stable

You can and must save your work at any time, for many reasons, but only in your local and distant branches.

Git as a temporary storage : with much care !

Only fully tested and finalized work can be pushed on a shared branch or the trunk.

You SHOULD save your work as commits to YOUR feature branch at least daily, in a as stable as possible state.

This non-shared branch SHOULD be pushed at least daily to protect you against local hard-disk failures (which WILL happen).

BUT, because ALL these commits will end-up into the trunk, ALL COMMITS must always have a clear commit message and include feature/bug ticket reference (PP-xxx or PUN-xxx).

This way, at the end, any Jira ticket is able to be traced to all parts of the related changes.

Developing a new feature

To add a new feature to the Punchplatform here is how to proceed:

1) Create a Jira Ticket

Info

Read the Jira procedure to understand which kind of ticket you need to create depending of the issue type

2) Create a Feature Branch

Say you want to create a feature my-feature in pp-core.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
cd pp-core

# place yourself on the origin/craig-stable branch
git checkout craig-stable 

# Pull and apply changes without create an unwanted 'merge commit'
git pull --rebase 

# create your feature branch prefixed with the jira ticket Id and add an explicit name  
git checkout -b pp-xxxx-my-feature 

Danger

do not call your branch 'craig-XXX' because these branches are protected. You will not be able to destroy them once done. Stick to pp-2734-somethingusefulbutshort

Ok, now that you are in a dedicated branch, you can safely develop your feature.

3) Commit Often

You can commit your intermediate progresses whenever you want, but only in your branch.

1
2
3
4
5
6
7
8
# get your current states, list your changes
git status 

# add files you want to commit
git add [path]

# choose your personal message, but always reference the feature/work you have worked for
git commit -m "pp-666 - my feature already does this, although unit-tests are red" 

4) Push Often

You can push your non-shared branch including your changes on the remote repository whenever you want.

1
2
# push your branch on remote repository (and track it)
git push origin -u pp-xxxx-my-feature 

5) Keep Your Branch Up-To-Date

Very often (at least once a day), refresh your branch with the latest stable sprint branch.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# First update your repository with remote changes 
# This only fetches the changes, it does nothing else.
# -a/--all fetches all remotes
# -p/--prune remove any references that no longer exist on the remote (tags, branches)
# -P/--prune-tags Before fetching, remove any local tags that no longer exist on the remote if --prune is enabled
git fetch -a -p -P 

# merge the remote stable into your branch 
# see tip below to rebase your local instead of remote craig-stable
git rebase origin/craig-stable

Resolve conflicts should you have some, and continue merge if needed. Your branch is now up to date.

merge your local instead your remote craig-stable

Alternatively you can switch to craig-stable, update it (git pull̀), switch back to your feature branch ̀pp-xxxx-my-feature, and merge craig-stable into your branch.
git rebase craig-stable

6) Request a Merge

Now, your feature is ready to be added on the stable branch (i.e craig-stable).

Note

Of course, always update your branch before requesting a merge.

Go to Gitlab and create à merge request.

Fix a bug

If you want to fix an official bug. Official bug is issued by the client and need to be clearly identified and can require a backport.

Considering you fix a bug my-fix in pp-core.

Before all, create a Jira Bug. Read Jira procedure to understand which one you should create.

Procedure is similar to Create a new feature.

Specific cases

Not creating branch

If your plan to create a small, small, small changes, corresponding to several tickets.

You can avoid to multiple branches. But But be careful to have a clean commit history !