This procedure explains how we use Git on our repositories.
The punchplatform team follows a trunk base development process. The most important observation is the following:
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.
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.
$ git pull --rebase origin craig-stable
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:
# BAD solution: Create a new commit with same message. git commit -m "PP-XXXX update prerequises in pp-core"
# 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:
# GOOD solution: Append changes to previous commit ! git commit --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
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
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¶
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
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
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.
# 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 (
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
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
Before all, create a Jira Bug. Read Jira procedure to understand which one you should create.
Procedure is similar to Create a new feature.
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 !