Git Workflow

In roadrunner we use a github workflow that makes use of feature branches, a develop branch (which is the default branch), an experimental release branch and a release branch. All new features, bug fixes, small changes etc. are conducted on a new branch from the develop branch.

git checkout develop # make sure were on develop
git checkout -b feature-branch

Note

If you have accidentally made changes to the develop branch, move them to a feature branch without committing. Do git switch -c feature-branch.

Now that you are in a new branch feature-branch any changes are completely isolated from the main develop branch, thus minimizing inclusion of accidental bugs into roadrunner. To push this new feature-branch to github do

# ensure changes are committed
git add -A
git commit -m "awesome new feature - tests pass"

# push to github. The ``feature-branch`` does not yet exist on github (the remote) so we need to create it
git push -u origin feature-branch

Whilst developing your feature on the feature-branch consider committing often, preferably at useful milestones, such as when you complete a class or even a set of methods. Be sure to use useful commit messages to aid yourself and others in understanding your commit.

Once complete - i.e. all your tests pass locally, you need to integrate these changes back into the develop branch. In roadrunner, we have disabled direct pushes to the develop, experimental-release and release branches, even for administrators. We do this because it is very easy to accidentally incorporate changes that break roadrunner. Even when all tests pass locally on your system, its possible that you’ve unintentionally broken something for another operating system. For this reason, we force all changes to be pulled through our azure-pipelines CI system before they can be merged.

To integrate your changes from feature-branch into develop, push your most recent changes and then create a pull request using the github browser. In depth instructions for creating a pull request can be found here. You should select feature-branch on the right and develop on the left in order to request that the contents of feature-branch be merged into develop.

This will automatically push your changes to azure-pipelines and begin building roadrunner on all systems in the cloud. If something breaks, you will not be given the option to merge feature-branch into develop. Instead you should follow the links to the roadrunner azure-pipelines interface to find out what broke your build. Fix the problems locally and commit and push them, like before. You do not need to do anything with the pull request, the changes will automatically be pulled once again through the azure-pipeline CI system.

Note

It is critical that your code is tested. If you do not test your code, then the azure pipelines build will not break even when roadrunner is broken. The integrity of roadrunner depends on your ability to test your code.