GIT WORKFLOW

Enable local config

Make sure to enable local configuration with the following commands
git config core.hooksPath .githooks
git config user.email youremail@domain.ext
git config user.name yourname

Commit syntax

Here is the commit norm we will follow for this project, the commit message is composed of a title line and a body.

The title MUST respects this format:
TAG TITLE (SCOPE):

The TAG can be one of the following only:
DOC : the commit is adding documentation, no code is involved.
ADD : adding a new feature, a new file of importance.
UPDATE : Updating an existing code/feature.
WIP : this is a work in progress, this is not allowed on master.
MERGE : Mandatory for a pull request. (only on a pull-request, should not be commited like that). FIX : self explanatory, this fixes an issue (make sure to include Close# to linked issues).
REWORK : rewriting the code to make it cleaner, this is not supposed to change the way it behaves.

The TITLE must be short and explicit.
SCOPE is optional, a typical use would be to explicit the scope where this belongs like (BACKEND) (CHAT) (GAME) etc.
The TITLE MUST end with : to explicit the end of the title

The body MUST be composed as such:
an empty line after the title
Multi-line description of the content of the commit.
Try to keep the description result oriented not issue oriented.
Possible close # for commits that solve issues.

Good practices also include not over-using the git add . and git add * (prefer git add -u and manual addition of new files)
Never use git commit -m use git commit instead and take the time to write decent messages.

Commit frequency

You SHOULD commit regularly, small commits make good commits.
If your commit is 100+ lines modified, it's likely you should have split it in several small commits.
The idea behind this is that if you split in several small commits and one of them includes an error you can git revert it easily.

Commit content

You MUST NOT commit broken code.
At the exception of the WIP tag, only allowed on initials-prefixed branches and removed from the other branches.
The use of WIP MUST stay an exception and MUST NOT become a habit.

Pull request frequency

Do not wait too long before making a pull request.
The way the workflow is built induces a need to regular merge of code.
An automation of tests will be built and added to the project (CI) therefore the sooner your merge your code, the sooner the unexpected behaviour or straight errors in your code will be noticed.

A short workflow example with commands

go on github and add the issue I'm working on to "work in progress" with me as contributor
git checkout master
git checkout -b aw/nameofthefeatureIwillbeworkingon

coding phase including several commits
git add myfile (please also use git status git add -p or git add -e)
git commit

git checkout master
git pull
git checkout aw/nameofthefeatureIwillbeworkingon
git rebase master
git push -f
go on github and create a pull request

OUR DETAILED FLOW:

Branch creation:

We always work on our own branch, which will be named in the same fashion : "[initials]/[feature]" == el/my_new_branch
To create such a branch
git checkout -b [initials]/[branch name]

/!\ No one is allowed to code on this branch, except its owner. If you need to test it or you need some of the code, you MUST create a new branch using the above command.

Branch rebase to apply changes after a Pull Request(PR):

Make sure you are on master with:
git checkout master or git switch master

Apply the changes to your local master branch:
git pull

Now you need to update your local [in]/[branch]:
git checkout [in]/[branch] or git switch [in]/[branch]
git rebase master

You may have conflicts to deal with. While they seem daunting at first, take a deep breath and carefully deal with them one by one.
If several commits are to be applied to your branch, you might have to deal with several waves of conflicts.
Fix the files, add them, then check the message on the terminal and type:
git rebase --continue
when prompted
/!\ At this stage, you MUST test your code to ensure that the conflicts were properly resolved and everything runs as smoothly as expected.
Once the rebase is complete you must force a push because the distant version of your branch and local version have now diverged.
git push --force This is normal and expected (and is one of the reasons some people do not like this workflow we chose).

WIP-free working tree:

We don't really want all the unfinished stages of a feature to appear on a MERGE commit, so we re-write history:
git rebase -i HEAD~[nd_of_commits_to_review]
A page will open where you will see each commit displayed on one line each, preceded with the keyword "pick".
example :

pick 07c5abd FIX LEAKS:
pick de9b1eb WIP THIS MUST GO:
pick 3e7ee36 WIP THIS TOO:
pick fa20af3 ADD THIS WILL STAY:

You want to merge #de9 #3e7 and #fa2 together, typing "squash" instead of "pick" before the #3e7 and #fa2.
/!\ SQUASH will meld the selected commit into the previous one : #de9 will be squashed with #3e7 but we don't select it /!\

pick 07c5abd FIX LEAKS:
pick de9b1eb WIP THIS MUST GO:
squash 3e7ee36 WIP THIS TOO:
squash fa20af3 ADD THIS WILL STAY:

This will be displayed:

# This is a combination of 3 commits.
# The first commit's message is:
FIX LEAKS:

# This is the 2nd commit message:

WIP THIS MUST GO:

# This is the 3rd commit message:

ADD THIS WILL STAY:

Add the last commit (the one you wish to keep) on top of the commit message and your good to go ! I usually keep the commit separators for clarity:

ADD THIS WILL STAY:
This is a combination of 3 commits.
The first commit's message is:
FIX LEAKS:

This is the 2nd commit message:

WIP THIS MUST GO:

This is the 3rd commit message:

ADD THIS WILL STAY:

If you had already pushed the commits you've just squashed, you will have to force the next push
git push --force

GIT ADD -P:

You may want to add some lines of your file instead of all of it (you want to commit your progress but not all your dev-messages "#std::cout<<"hey"<<std::endl;").
git add -p filename will interactively highlight block of lines which had undergone a change since the last commit.

• if you want to keep those lines as they are, type "y" and you will be shown the following ones.
• if you do not, type "e" and the editor will give you the possiblity to single out each line from the block and decide whether you want to add them.
• you can also type "?" to see an overview of the options available to you

When you reach the end of the file, commit as usual.