Git Workflow

If you are completely new to Git and GitLab, start from reading the Git Basics or maybe A Simple Guide to Git.

Also you can check these:

• Interactive Git Tutorials
• Git History Visualizer

You can also look at the Cheat Sheet for some quick commands.

About this Repository

First of all, a few things about this repo:

• In the Files section you can find the build system (sbs), the code (in src/) and external libraries (in libs/).
• The Issues section contains all the issues/enhancements that have to be discussed together. If you find a bug/problem, that's the right place to post it.

Our Branching Model

In Boardcore there is a main branch: everything that's here has been tested and it's working (or at least it should).

WARNING: You should NEVER commit directly to the main

To make changes to the software you should use temporary branches, such as:

• development branches: are branched off from main and exist for a limited amount of time for developing a specific feature (e.g. somesensor).
• hotfix branches: when a bug is found on the main, a branch is created to find a fix to that bug. When the problem is solved, the branch will be merged with the main branch before being cancelled.

Branch Workflow

• A new feature is required (e.g. a barometer driver)
• A new branch called barometer is created from main (you can do it locally)

git pull
git checkout -b barometer

• Commits are made on the branch

<modify files>
git status
git add name-of-modified-file
git commit -m "[BAROMETER] Added barometer driver."

• Frequently git pull and git rebase main to keep aligned to the main branch.
• When it's ready, make sure it's 0 commits behind main and TEST it one last time.
• Make a merge request to merge the branch back into the main branch and set the current IPTL as the reviewer.
• If some issues are open in the merge request, you will need to solve all of them before obtaining the approval from the reviewer.
• In case you find an issue regarding a whole another topic, it would be best opening an issue, another branch and the corresponding merge request.
• Temporary branches should be as "atomic" as possible. This means that the only connection that they have should be the main branch and NOT other temporary branches.
• Once the code is ready and the reviewer likes it, contact your IPTL to approve the merge request.
• Finally, when ready to merge 99% of the times you will need to squash (aggregate) the commits you made (to not fill the main branch history with minor details) but, if this is not the case and you need to leave more than one commit message, then you should refer to an interactive rebase.

Commits

Commits are the core of your team work, because they are the way in which you communicate to the team how you changed the code. For this reason, you have to think before you commit, and try to write good commit messages.

Some simple rules:

1. Write meaningful commit messages, with a short explanation on the top and a more specific one under:

   [Topic] short message
   *Blank line*
   Long explanation

   For example

   [Wiki] Add Git Workflow page
   
   The page contains the description of our workflow with git, in particular:
   - Basics(pull, add, commit, push)
   - Branching(main, development and hotfixes)
   - Commits(how to write commit messages and when to commit)

   Do this, and everyone will love you - including yourself, when you'll read your code after a month from when you last wrote it..

2. One task = One commit

   Group together in the same commit the changes that were made for the same task: if you're about to write something like

   Fixed bug in Class.cpp and Added something else in another Class.cpp

   Think twice! Probably you should be doing two separate commits.

Interactive Rebase

WARNING: You should NEVER try to rewrite the main branch history

Sometimes to fix some mistakes in temporary branches or to simply squash some intermediate commits you will need to interactively rebase the branch. To do so, you just need to execute a simple command:

git rebase -i "hash of the commit you whant to start from"

After this command, you will be prompted with a terminal editor with all the commits starting from the one you selected.

An example of text could be this:

pick 45c1024e [ModuleManager] Added static_asserts
pick 5871115d [ModuleManager] added assert to the access method
pick 18322dcb [ModuleManager] Interpreted module manager as singleton (to be discussed)
pick 0c8689c0 [ModuleManager] Added destructor to avoid memory leaks
pick 40dbd197 [ModuleManager] Minor fix about destructor
pick 9ab03824 [ModuleManager] Changed policy about get a non registered module and the possibility to remove modules

If you replace pick with the commands that are listed below the commits (like reword, edit, squash, drop..) you will be able to modify the history.
Remember that after any modification about the history, to correctly update the remote, you will need a force push:

git push -f

Be really careful, a force push could damage permanently your previous work.

Here you will find some useful guidelines about the interactive rebase.

What's Next

Now that you know how to work on this repository, you can read the Coding Guidelines.