Contributing: git development workflow

This documentation aims to document how contributors should work when using Git, GitHub, and the development workflow. This workflow supports the parallel development on multiple major versions of CoolProp. However, older versions only get bug fixes and no new features. This Git workflow is greatly inspired by the development workflow of the Structured Dynamics project. Very similar instructions and workflow can be found at The Beginner's Guide to Contributing to a Github Project

Contributors vs Collaborators

The CoolProp collaboration team will use a slightly different Collaboration Workflow

Contributor Workflow

Overview

Who is a contributor?

A contributor can be anyone! It could be you. Continue reading this section if you wish to get involved and contribute back to CoolProp.

Initial Setup

• Install Git on your local machine - There are a number of versions that will work, but we'll be working in the command line mode here.
• Setup a GitHub account.
• Fork the repository of the project - This creates a copy of the entirety of the CoolProp repository in your account MyGitHubAccount/CoolProp that you created in the previous step. This location will typically be called Origin by git.
• Clone your fork locally - This creates a copy of your GitHub repository (above) on your local machine. This is where you will do your development and testing and make pull requests back to the Upstream repository, CoolProp/CoolProp

$ git clone https://github.com/MyGitHubAccount/coolprop.git --recursive

• Enter the CoolProp directory and add the upstream remote

$ cd CoolProp
$ git remote add upstream https://github.com/CoolProp/CoolProp.git

• Check that your remotes are set up properly. The command below should list your origin and upstream remotes. Just remember that origin is your forked copy (on your user account) that you made of the upstream (CoolProp/CoolProp) repository.

$ git remote -v

Keeping your master up-to-date!

Once all this is done, you’ll be able to keep your local master up to date with the simple command:

$ git checkout master
$ git pull --rebase upstream master

You will also need to push any updates to your forked repository on Github with:

$ git push origin master

Branching Model

The following names will be used to differentiate between the different repositories:

• upstream - The “official” CoolProp repository (what is on CoolProp's GitHub account)
• origin - Your fork of the official repository on GitHub (what is on your GitHub account)
• local - This will be your local clone of origin (what is on your computer)

As a contributor you will push your completed local topic branch to origin. As a contributor you will pull updates from upstream.

Primary Branches

The upstream repository holds the following primary branch:

• upstream/master Development towards the next release.
• upstream/release Release versions of the code - no development.
• There may be other branches from time to time (develop, release, etc.) that the main collaboration team uses to do their own development, but you don't need to worry about them at this time.

These branches exist in parallel, are permanent and are defined as follows:

upstream/master is the branch where the source code of HEAD always reflects the latest version. Each released major stable version will be a tagged commit in the upstream/master branch.

NOTE You should never commit to your forked origin/master. Changes to origin/master will never be merged into upstream/master. All work must be done in a topic branch, which are explained below.

Topic Branches

Topic branches are where contributors develop bug fixes, new features, etc. so that they can be easily merged to upstream/master by the project owners. They must follow a few simple rules as listed below:

• Should branch off from: master branch.
• Should be pushed to: origin (where a pull request can be initiated to the upstream repository).
• Should not be merged directly back into: local master branch. The local master branch should be kept up-to-date by pulling from the upstream/master once your pull requests have been accepted and merged into the upstream repository by the owners.
• Branch naming convention: anything except master. If the topic is related to a GitHub issue on the CoolProp (upstream) project, then name it topic-# where # is the number of the GitHub issue, i.e. topic-13. You should consider creating an issue on that issue tracker before starting a new topic branch. That way, people will be able to know what you are doing with your topic branch.

Topic branches are used to develop new features and fix reported issues. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown. The essence of a topic branch is that it exists as long as the feature is in development, but will eventually be merged back into master or a x.y.z branch (to add the new feature or bugfix to a next release) or discarded (in case of a disappointing experiment).

Topic branches should exist in your local and origin repositories only, there is no need for them to exist in upstream.

Working on topic branches

First create an appropriately named branch. When starting work on a new topic, make sure that

1. Your local master is up-to-date with upstream/master
2. You use the default starting point (master HEAD)

$ git branch topic-13
$ git checkout topic-13
Switched to branch 'topic-13'

...or alternatively use the convenience option (-b) on checkout to create the branch and check it out in one step...

$ git checkout -b topic-13
Switched to a new branch "topic-13"

Commit your Work

Now do some work, make some changes then commit them:

$ git status
$ git commit <filespec>

Or, if you want to make changes to multiple files under one commit message, add them to the tracking list, then issue one commit. You can add the commit message to the command line as well.

$ git status
$ git add <filespec1>
$ git add <filespec2>
$ git add <filespec3>
etc.
$ git commit -m "Put your commit message here that briefly describes your commit."

Merge In Any Recent Changes from the Upstream Remote

Next, merge or rebase your commit against upstream/master. With your work done in a local topic branch, you’ll want to assist upstream merge by rebasing your commits. You can either do this manually with fetch then rebase, or use the pull --rebase shortcut. You may encounter merge conflicts, which you should fix and then mark as fixed with add, and then continue rebasing with rebase --continue. At any stage, you can abort the rebase with rebase --abort unlike nasty merges which will leave files strewn everywhere.

$ git fetch upstream
$ git rebase upstream/master topic-13

or (combine fetch/merge in one step):

$ git pull --rebase upstream master

CAUTION You should not rebase once you have pushed your branch to origin.

NOTE Using rebase instead of merge will bring in any changes from upstream and then replay your commits on top of the updated branch. The benefit of this is that it will not generate a merge commit in the branch's commit log. If you fetch from upstream many times during your development (which you should do periodically to avoid conflicts), a merge will generate merge commits each time, cluttering your history with unnecessary entries. rebase will give your upstream collaborator a much cleaner history to review.

If you need to pull master into your branch after it has already been pushed remotely, simply use:

$ git pull upstream master

This will, however, generate a merge commit in your history.

Push Your Development Branch to Origin

Next, push your development branch to origin (not your local master! - rookie mistake):

$ git push origin topic-13
To git@github.com:hobouser/CoolProp.git
    * [new branch]      topic-13 -> topic-13

WARNING Do not pull your changes into your local master, push master to origin, and generate your pull request from there; it will send the complete commit history of your local repository with the pull request and annoy your upstream collaborator on a grand scale.

This puts your development branch on your forked repository on GitHub. Now you are ready to send a pull request from this branch on origin to the upstream repository (and update the GitHub issue tracker) to let a collaborator know your branch is ready to be merged.

• Open your forked repository on Github in your browser
• Select the new branch that you just pushed from the drop-down
• Submit a new pull request, entering a title and a brief description of the request and the commits contained within

The collaborator may suggest modifications to your development branch before it can be merged into the upstream repository. In this case, make and commit the additional changes and push the modified branch up to origin again. The original pull request will automatically be modified with the new modifications.

Topic Branch Cleanup

Once your work has been merged by the branch maintainer, it will no longer be necessary to keep the local branch or remote branch, so you can remove them!

Sync your local master, pulling in your newly accepted code:

$ git checkout master
$ git pull --rebase upstream master

Remove your local branch using -d to ensure that it has been merged by upstream. Branch -d will not delete a branch that is not an ancestor of your current head.

From the git-branch man page:

-d  Delete a branch. The branch must be fully merged in HEAD.
-D  Delete a branch irrespective of its merged status.

Remove your local branch:

$ git branch -d topic-13

Remove your remote branch at origin:

$ git push origin :topic-13

One for the Road