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 often commit, 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¶
Development process¶
Ticketing¶
Every development should be linked to a Gitlab ticket, either a bug or a feature. Even a small bug that doesn't require a lot of coding. The idea behind this is to ensure every development can be traced, and our release note, which is made based on gitlab tickets, is as exhaustive as possible.
To create a ticket on gitlab, simply choose the right template (feature/bug), and follow the instructions on how to fill the description. You should then set the correct labels and milestone, in order to ease the back-log exploration.
The only exceptions to this rule are quick fixes/improvements of the documentation and quick critical fixes when the compilation doesn't succeed (unit tests, syntax errors...).
Branch naming¶
Use the gitlab ticket interface to create the associated branch. The branch name should look like :
XXXX-my-ticket-title
Commit naming and ticketing,¶
Every development should be linked to a Gitlab ticket, either a bug or a feature. Therefore, every commit message should contain a ticket reference. A valid commit message should match the format :
#<ticket number> <your message>
Example :
#1264 Handling a minor bug
When dealing with documentation fixes, use the ticket number #0000.
When dealing with build fixes, use the ticket number #0001.
Always try to 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.
Merge request¶
Every ticket-based development with more than two lines of code changes should go through a merge request. This is important, not only to double-check that the fix/feature is working and solving the issue, but also to ensure the code is understandable and validated by another developer, and the documentation is clearly filled.
To create a merge request, simply create a new one in gitlab and follow the template.
Tick the "squash commits" box if possible. Do not squash commits that contains both a renaming, and a modification of the same file. This would erase trace of the renaming and lose all git history for this file (not to mention merge conflicts in the future). The author of the merge request should be the one to press merge.
Merge¶
When your development is done, you need to immediately merge your target branch into the upper ones, i.e. the following versions. Simply follow the versions pattern :
// This is an example. It may not contains the actual punch versions
6.3 -> 6.4 -> 7.0...
This is very important and should be done immediately after you merge into the target branch !
It prevents another developer from facing your potential merge conflicts that he may not be able to resolve. Make sure
to use the git pull command (and not rebase).
Some big merge may create a lot of conflicts, that take time to resolve and require further testing. During the resolution and testing period, you're preventing everyone from pushing new developments, and if they do, you may have to do the resolution again... To prevent this situation, duplicate your target branch and try the merge on that duplicate. When it's all done, you only have to transfer the modification during the actual merge. This way, the actual resolution will be smoother, faster and hopefully not blocking.
Git Setup and Tips¶
Deal with previous local commit¶
The following sequence is very frequent:
cd libraries
# I edit something
vim README.md
git add README.md
git commit -m "#XXXX update prerequisites in libraries"
# 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 "#XXXX update prerequisites in libraries"
This too:
# BAD solution: Create an other commit with other message.
git commit -m "#XXXX fix update prerequisites in libraries"
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
Amend --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 fall 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 should have to test your development
Write useful commit message¶
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 (#xxxx).
This way, at the end, any Gitlab ticket is able to be traced to all parts of the related changes.
Keep Your Branch Up-To-Date¶
Very often (at least once a day), refresh your branch with the latest stable sprint branch.
# 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 6.3
git rebase origin/6.3
Resolve conflicts should you have some, and continue to merge if needed. Your branch is now up to date.
merge your local instead your remote 6.3
Alternatively you can switch to 6.3, update it (git pull̀),
switch back to your feature branch ̀xxxx-my-feature, and merge 6.3 into your branch.git rebase 6.3`