Git Workflow

Basics

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

These are some of the terms you'll need to know:

1. pull: fetch the most recent version of the code (after you cloned the repository).
2. add: "stage" your changes for the commit.
3. commit: group together changes to make them final (see below).
4. push: send your changes on the Github repo (the origin).

On a bigger scale, changes to the code can be made on different branches, which are different versions of the same project that can be merged into each other.

5. checkout <name-of-branch>: change working branch.
6. merge <another-branch>: import all the changes made in another branch (can produce merge conflicts when the same file has been modified in different ways: you have to resolve them in order to merge).
7. pull request: ask for your branch to be merged with the original branch (it's better if you add some reviewers to check that everything's ok before merging).

Boardcore Branches

This branching model was inspired by http://nvie.com/posts/a-successful-git-branching-model/.

In Boardcore there are two main branches:

• The master branch: is the main branch, everything's that here has been tested and it's working (or at least it should).
• The testing branch: is where development takes places. When a new feature is ready, it has to work with the rest of the code and then, only when everything's working, it can be merged with the master.

⚠️ WARNING: You should NEVER commit directly to the master

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

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

Boardcore Workflow

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

git pull
git checkout -b barometer-dev

• 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 merge testing to keep aligned to the testing branch.
• When it's ready, make sure it's 0 commits behind testing and TEST it one last time.

python sbs -v

• Make a pull request to merge the branch back into the testing branch
• In testing futher integration tests occur, and then everything is merged on the master

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 meaninful 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(master, testing, 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. Not less, not more.

   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.

What's Next

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