This document proposes the GitHub Branching Strategy and ‘workflow’ for use in OpenWIS development.
The document is written in a chronological order from repository creation and should mirror how the branches and forks interact through the release cycle.
The OpenWIS repository has been created by the Met Office, which is acting as the GitHub administrator for the partners . The repository can be accessed at https://github.com/OpenWIS/openwis and requests for access can be made via email@example.com or firstname.lastname@example.org.
When the new (original) repository was created it had one basic empty branch, master.
The first commit of code to this repository was openwis-3.11 released in July 2013. This code was then ‘tagged’ to create a known baseline.
The master branch should represent the production or production-ready code, and therefore should not contain any development code. A new branch “develop” has been created for this very reason.
When openwis-3.12 was committed in February 2014, the code was committed to the develop branch, merged to the master branch and tagged (again to provide a baseline)
The initial population was completed in the single repository. The repository was cloned to a local workstation and then new commits were made and the changes _pushed _back to the GitHub repository.
However there will be multiple developers from the association working on OpenWIS at the same time: we need a means of isolating the development so as to reduce conflicts. Rather than have the Met Office designate read/write permissions to the repository, we will allow partners to ‘fork’ the repository using GitHub’s Fork and Pull Model
The Fork & Pull Model lets anyone fork an existing repository and push changes to their personal fork without requiring access to be granted to the source repository. The changes must then be pulled into the source repository by the project maintainer – a named user from each partner.
This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination.
Forking will allow developers to take exact ‘mirrors’ of the OpenWIS repository and make changes without affecting the original.
Log in to GitHub and browse to the repository - https://github.com/OpenWIS/openwis. You will see a ‘Fork’ button in the top left corner, click on Fork
You will be given an option of where to fork this repository, select your GitHub username. After a short delay you will be presented with your forked repository. You now have full read/write control over this repository.
Whilst you can make as many forks as required, there are two real options :
- one fork for each user, or;
- one fork for each partner
Both have benefits and drawbacks, but both methods will use the below methodology.
If you decide to have one fork per user, you will need to do a lot more merging between the forks to ensure everyone’s changes end up in one repository that can be merged back to the original. If you decide to create one fork per partner, then there is less fork merging but you may have to administer access rights to ensure all required users have access to the fork.
It is probably easier to have one fork per partner.
The simplest way of working is to change code and commit directly to the develop branch. However for a number of reasons, this is not recommended. To enable you to isolate code for individual bug fixes or new features you should create a new feature branch off of develop for each bug or feature you want to implement. This is achieved by using the git branch command (or similar if you are using a Graphical User Interface or Integrated Development Environment).
This allows code to be committed to individual branches specifically created for a unit of work and allows it to be merged back to the develop branch without pulling in any other units of work.
If you are working with the one fork per partner model, then the individual feature/bug branches also ensure that developers’ code is isolated from each other’s and as a result one developer’s broken, erroneous, trial or mid-development code does not affect that of other developers working on different feature branches.
Remember all of these branches are in your fork, and are not affecting the original.
When you have made your changes in the fork, you need to merge your fork back to the original. GitHub has detailed information on how to merge your changes in the fork back to the original repository - https://help.github.com/articles/using-pull-requests. When you create a pull request all users will be added as watchers so that they can collaborate and discuss the changes.
PLEASE ENSURE ENSURE THAT YOU DO NOT MERGE TO THE MASTER BRANCH IN THE ORIGINAL, MERGE TO DEVELOP
When the release is deemed production ready the OpenWIS:develop branch (which will contain the bug fixes and features worked on for that release) will be merged to OpenWIS:master and tagged. The master branch on the original open-wis repository is only for Production and Production Ready code.
Currently, all members have write access meaning they can fork, commit to a fork and merge back to the original as well as commit directly to the original.
The partners need to agree if this model is suitable or if a workflow such as the Integration-Manager-Workflow should be applied. This would allow all developers to fork and commit to their forks, but only allow named integration managers to merge pull requests and keep the original repository clear of rogue commits.