Development workflow

General basics:

  • Bugfixes and features are developed in a branch to isolate others from (unintended) side-effects of your work until feature is complete, or bug is fixed

  • Typically, we only work towards one major.minor release series at a time, so at the moment we do not have separate branches for different release series; therefore, the instructions below assume that all branches start from (and are merged back into) master

  • When new commits are pushed to our firmware and software repos on GitHub, the source code is automatically built and tested. Developers can only merge the branch that they’re working on into the master branch if the tip of their development branch passes the automated build + tests.

Standard workflow for main developers

The standard workflow for main developers is explained in detail below, but can be briefly summarised by the following diagram:

_images/IPbus_git_workflow.svg


Step 0: Open a ticket on GitHub

Describe the feature that you’re adding, or the bug that you’re fixing, in a GitHub issue - for the firmware click here, for the software here.

Note

When opening the issue, if possible, please remember to:

  • Add a label: bug, enhancement or task

  • Set the assignee

  • Set the milestone to the first major/minor/patch release in which you want to include this feature/bugfix

Step 1: Create a branch

In case you haven’t already got a local copy of the repo, clone it:

git clone git@github.com:ipbus/ipbus-software.git

Or if you’re using an existing local copy, pull in recent commits from GitHub, in order to make sure that you don’t start the branch on an old commit:

git pull

Finally, create the branch, with name beginning bug/, task/ or feature/, e.g:

git branch task/cleanup-my-code start-point

where start-point is the name of the branch (often master), or the hash of the commit, that this branch should start from.

Tip: git checkout -b task/cleanup-my-code start-point will both create this branch, and check it out, in a single command.

Step 2: Develop the feature / bugfix in a dedicated branch

  1. Check out the newly-created branch:

git checkout task/cleanup-my-code

  1. The fun part: Write code that implements the feature, or fixes the bug

  • Along the way, commit your code to the branch. For each commit you need to:

    • First add the relevant changes to the index (often called the “staging area”), git add myFile

    • Then create the commit, git commit -m "My message"

  • The commit messages should reference the related GitHub issue, e.g. by adding refs #42 or fixes #42 to the message

  1. If any other branches have been merged into the master during the time you’ve been working on your local feature branch, you can update your feature branch to start from the new tip of the master branch by running the rebase command (which changes the “base commit” of your branch)

# Pull master's new commits down to your local repo
git checkout master
git pull
# Checkout feature branch again, and rebase it
git checkout task/cleanup-my-code
git rebase master task/cleanup-my-code

  1. Push the commits to GitHub

The commits are initially only stored in your local repo, and need to be pushed to GitHub to be shared with other people, or to merge them back into the source branch. This can be done as follows (assuming the GitHub remote is named origin in your repo)

git push --set-upstream origin task/cleanup-my-code

Step 3: Open a pull request

In order to merge this branch back into the base branch (master or the release branch), open a pull request - for the firmware click here, for the software here

Once the automated build and test jobs have reported that the feature branch passes all requirements, you can tell GitHub to merge the feature branch back into the base branch by clicking the “Merge pull request” button near the bottom of the pull request’s page.

After the merge, your bugfix or new feature is included in the master branch, and you can move onto other work.

Workflow for external contributors

Todo

Fill in - fork-based workflow

Release branches

Todo

Maybe improve diagram.

This release branch strategy is largely based on the “GitLab flow” article at https://about.gitlab.com/2014/09/29/gitlab-flow/

If only one minor release of the software is currently being worked on, then all of the branches for features and bugfixes will be created from, and be merged back into, the master branch.

However, if multiple minor releases of the software are currently being worked on - e.g. you’re still fixing bugs for release series X.Y, and also working on ABI-backward-incompatible features for version X.Y+1.0 - then the different minor releases will have to be developed in different branches. The highest-numbered minor release should be developed in the master branch; a release branch, with name of format release-X-Y, should be used for each the other minor release series being actively developed, as shown in the diagram below:

_images/IPbus_release_branch_workflow.svg

N.B.

  • Release branches should be created from the master branch as late as possible - e.g. in the last commit preceeding a backward-incompatible change - in order to minimise the number of bugfix commits that you have to apply to multiple branches.

  • Bugfixes: upstream first. When one or more release branches exist, if possible, bug fixes should first be merged into the master branch, and then cherry-picked into the release branch(es). The motivation for this convention is to avoid forgetting to include the bugfix in the master branch (you’re typically less likely to forget to include it in the release branches, since they’re often closer to the next release tag).