Git worflow for a better development

Table of Contents

• Git configuration
• Git cheat sheet
  • Commit message
  • Working with branches
  • Tagging the code
• Workflow explained
• Email notification

This page explains the basic git workflow used in GBS to have a clean and easy development cycle

Git configuration

The firs step is to make sure that your git has the correct basic configuration, i.e. you have set up a username and an email address. This will ensure a clean history and allows one to quickly and easily identify you.

The basic configuration is done as follows

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email your@email.address

where FIRST_NAME and LAST_NAME, and your@email.address have to be replaced with the correct information.

At any time, you can check your configuration using

git config --list

Note

If you already have a git configuration that does not correspond to this one, you can change it locally only for the GBS project. To do that, place yourself in the GBS repository and replace the --global option by --local.

Git cheat sheet

Commit message

Keep in mind that the commit messages are often used in the debugging process to identify when and where a bug was introduced. It is then important to explain clearly and concisely what you have done in a commit.

https://xkcd.com/1296/

Here are some rules to apply to all your commit messages:

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters (if you cannot describe your commit with more or less 50 characters, you should probably make several commits !)
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

For example:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like log, shortlog
and rebase can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

• Bullet points are okay, too
• Typically a hyphen or asterisk is used for the bullet, preceded
  by a single space, with blank lines in between, but conventions
  vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Note

If you don't want to spend too much time writing commit messages during the development phase, you can do it later using the interactive rebase (git rebase -i) as long as you have not already pushed your commits !

Working with branches

It may be useful to isolate your work from the master branch to ensure that what your doing will not impact the production branch until it is fully tested. In git, it is very easy to do so by using the concept of branches. Here is a small summary on how to use them.

• First, create a feature branch (the name is arbitrary):

  git branch feature

  and check it out:

  git checkout feature

  You are now on the feature branch and all the work you will be doing is isolated from the master branch. You can then develop the code without worrying about the tests, etc.

  Note

  Both steps can be summarized into one command:

  git checkout -b feature

• Whenever there is a push to the master that you want to incorporate into the feature branch, you can use the merge command:

  git checkout feature # This is to ensure you are on the feature branch
  git merge master     # This will incorporate the changes from the master to the feature branch

  Note

  If there are not particular reasons not to do so, you are strongly encouraged to merge the master branch to your feature branch as soon as there is a push. This will, hopefully, avoid long and painful conflict resolutions.

• Once your work is tested and documented, it is ready to be published in the master branch, you can merge it to the later:

  git checkout master              # To ensure you are on the master branch
  git merge --no-ff feature        # To merge your work into master
  git branch --delete feature      # To delete the now obsolete feature branch
  git push --delete origin feature # To remove your feature branch if you pushed it (MAKE SURE THAT NOBODY IS USING IT)

  If you have always merged the changes from the master into your branch, the last merge should be executed without conflicts.

  Note

  The optional --no-ff option allows to keep a trace of the branch in the history which may be useful to track the developments. It is also important to symbolize that only the merge commit is ensured to be tested and stable.

• Finally, since you have probably added a new functionality or corrected a bug, you can proceed to the next section to know how to tag and change the code version number.

Tagging the code

Use the following command to create an annotated tag with git:

git tag -a vX.Y.Z <commit hash>

where vX.Y.Z is the new version of the code and <commit hash> is the hash of the commit you want to tag. Note that the commit hash is not required if you currently have it checked out. The git tag command will open a text editor and you will be asked to enter a meaningful message to describe the version.

Note

Be sure the version number you use is not already used. To check that, first update your repository with git fetch origin and then check the last tagged version with git tag -l v*.

Once the version has been created, push it to the server using

git push --tags origin

Workflow explained

In GBS, we use a simplified variation of the GitFlow to maintain a clean and deployable master branch that can be used for prodution at any time. The golden rules are the following:

• Any changes to the code must be done in separate a short-lived feature branch with an explicit name defining the current work. Typically, all the feature branches are named following the convention feature/<feature_name> e.g. feature/new_boundary_conditions.
• The only exception to the first rule is for bugfixes that can be done in a single commit or changes that does not affect the simulation, e.g. adding documentation to the code.

With those two golden rules in mind, let us make a quick example for the development of a new Poisson solver.

1. Create a feature branch:

   git checkout -b feature/new_Poisson_solver

2. Make your changes and commit them according to the standard git workflow.
3. Once you are finished with the development, make sure you have tested it and documented it. Ideally, you should place reproducible tests in the corresponding folder so that anyone can launch them.
4. Merge the master branch into your feature branch:

   git merge master

   and make sure everything is working properly.
5. Merge your development back into the master branch and delete the feature branch:

   git checkout master                                 # Checkout the master branch
   git merge --no-ff feature/new_Poisson_solver        # Merge back your feature branch
   git branch --delete feature/new_Poisson_solver      # Delete locally the feature branch
   git push origin --delete feature/new_Poisson_solver # Delete also the remote copy on the server

6. Tag the code if needed and push the updated master branch

   git tag -a vX.Y.Z             # Tag the code if needed
   git push --tags origin master # Push the updated master branch as weel as the tag

Email notification

You may want to receive email notification for each push that occurs on the GBS repository. For this, you need to setup an Herald rule on c4science:

1. On the search bar, look for Herald and select Herald: Create notification rules
2. Click on Create Herald Rule on the top right of thw window and select Commit Hook: Commit Content and then Personal
3. Give a name to your rule and on the Conditions panel, select all of, Repository, is any of, and rGBS GBS
4. Verify that in the Action panel the selected action is Send me an emailand save the rule