For every development team, behind them lies a terrific development workflow. Until recently I hadn't found a great way to manage my own projects, let alone the projects for the team. We had migrated git instances more than I'd ever like in a few projects (another story), but never had time to develop a good workflow for how we would all progress the software.

The team and I finally had a moment to breath and we sat to discuss how best to work moving forward. We developed a few guidelines...

  • The master branch must always be 'demo' capable (i.e. nightly builds, integration tests, etc. always pass)
  • Have a way to report upstream (i.e. to upper management) what the team is currently working on and what they had accomplished
  • Incorporate a management strategy such that milestones (i.e. major and minor version releases) can be tracked and dated
  • Keep the process as minimal as possible for the developer
  • Must incorporate Github (who doesn't use Github?)

We looked at the multiple git workflows already present (Github Flow, branching models, Atlassian models) and found a hybrid of a few of them would work best. We really liked the idea of the branching model listed above, but found it very cumbersome on the developer. Likewise we liked the Github Flow model, but it didn't incorporate releases (i.e. milestones). Merging them we came up with what we are using today with great success.


For this model to work one person will need to take ownership of creating a majority of the issues (backlog items, etc.) and all milestones, assigning milestone dates (if necessary), and ensuring the developers are properly educated on the development process. This person typically holds a title like team lead, technical lead, or scrum master if you're using agile development, but for simplicity we'll just refer to this person as the hub lead (since it sounds new and fun!) for the remainder of the post.


All milestones act as official product releases and are labeled with semantic versioning meaning they'll look something like:

  • 0.3.0
  • 1.0.0
  • 2.4.0

Note that the patch version is always 0 in a milestone. Patch increments are covered later (they still exist), but patch increments will never show within a milestone.

Milestones are tracked through Github and made up of a series of issues. Once all issues are completed for a given milestone it is closed and tagged through Git creating a release on Github.

Major and Minor Version Increments

Incrementing of the major and minor version are stipulated through the semantic versioning guide so use discretion when updating either one. For reference:

  1. MAJOR version when you make incompatible API changes, and
  2. MINOR version when you add functionality in a backwards-compatible manner

It is up to the hub lead to ensure that a given issue's completion within a given milestone complies with that milestone's verion.

For example, if issue #12 were API breaking upon completion (i.e. a major version increment) and the current software version were at 1.4.8 then that issue could only be assigned to any milestone with version 2.*.* or greater. It would be an error if that issue were assigned to, say, the milestone 1.5.0.

Patch Version Increments

For a patch version increment to occur, thus triggering a patch release (i.e. a release with an incremented patch value), two things must occur:

  1. An error must have been found (more on error labels below)
  2. An issue must have been created within the project through Github for that error

Once those two items are fulfilled the team can then begin to work on the error and, once completed, will tag and release a new version.


Issues fall into four categories which are described in detail below. These categories correspond directly with the available labels one can associate with an issue within Github. The primary concept related to issues is that all issues will have a corresponding branch on the remote tree to denote it's status.

When a developer picks up an issue to work on they will first make a new branch descriptive to that issue followed by the issue number that Github provided it. The naming convention used is as follows:


There should be no whitespace within the branch name. The descriptive issue name is typically pulled directly from the title of the issue as seen in Github.

For example if there was an issue labeled "Add docstrings" with issue number 12 then a developer would checkout a new branch as such:

git checkout -b add-docstrings_2

followed immediately by:

git push --all

The --all flag will push the branch to the remote repository denoting to the rest of the world that this issue is being worked on. This technique helps to denote to the rest of the team and beyond who is working on what within the project.

Now onto the four primary labels we use. Remember, labels are merely tags that the hub lead will use within Github to denote the type of work corresponding to each issue. Again, this is used to be more transparent in the development workflow for customers and external parties.


A feature is a completely new element to the project. It will typically involve a majority of the code written to be new code not previously in the project and provide a new capability visible to the end user.


Enhancements are unlike features in that they typically will enhance a previous capability already present in the application. The majority of code written will still likely be new code, but the additional capability might not be readily apparent to the end user.


Bugs are minor problems within the code. They do not require immediate fixes (i.e. halt all other work) because, if one were triggered, the application could still function with its core capabilities. Bugs are not capable of incrementing the patch version of a release, but will instead be added into the current working milestone.


An error is unlike a bug in that this will require immediate rectification and typically, once triggered, will halt the application from performing its core capabilities. Errors, once reported and fixed, will increment the patch version and generate a new release.


My team and I have been using this new development workflow for roughly two months now and we've seen great benefits from it already. Upper management and our customers enjoy the transparency of our efforts while developers stay smiling because the process doesn't hamstring their previous individual workflow. I personally have taken over the hub lead role and don't find it very intrusive to my schedule either as Github makes it very efficient to create issues and milestones, assign issues to milestones, label issues, and cut releases. If anyone decides to try this approach for their team I'd love to hear how it goes, successful or otherwise, so feel free to let me know!