A possible strategy for using GIT and working with branches.

In this part 1: working on new developments.

In part 2: bug fixes on the released code

Branch management with GitHub and Firmware

I am suggesting a GitHub process, but it translates to other platforms with pull request support, E.g.: Azure DevOps, GitLab, Bitbucket, ...

The examples are using the repository of the eLoad.

I am using a single repository but it works virtually the same if contributors work from their own forked repository.

 

 

Branch Strategy Principles

 

Single Branch

You can work with a single branch. Git always comes with a default master branch.

If all you want to do is have a version controlled repository, you can give commit access to all contributors and that's that.

No need to read any further. You're good .

 

In the images, the vertical lines represent Git branches. The horizontal arrows are actions.

 

Feature Branches

If you want to control what goes into the master (or any meaningful) branch, you can use the feature branch strategy.

In that case, you allow contributors to create their own branches on the fly*2. You don't give them commit access to the master branch.

Feature branches are short-lived by design. They are meant to work on one aspect of the software.

The developer works in that branch and has all the advantages of version control. Changes are tracked, but they stay safely in that feature branch.

It doesn't matter if non-working or partial code is checked in. The "official" code base is not impacted.

 

Once development is deemed finished - you can set rules here if wanted, like all test cases passed, code style checks passed, .... - the developer can create a pull request.

This is where the hosting site matters*1. They support this process to generate the request and get it merged into the official branch.

Once the repository admins accept that pull request, the feature branch is typically deleted because it has lived its life. No need to keep that.

The change will be eternally traceable via the pull request that stays in the repository forever.

 

Branch Policy

The hosting platforms all have some way to set the rules for branches.

You can set who can commit / merge, what type of merges are allowed, who's approval is needed, or no rules at all (typical for feature branches).

If you want your master branch managed, then restrict commit, and set at least one approver.

A pull request creator should not be able to accept their own changes.

This will take care that no one can directly write into the managed branch, and everything can be reviewed and accepted before merging features.

 

If you have an unpopular open source project and you're the only contributor, you can still use this approach, but enable "admin override".

In that case you can accept your own pull requests. Not an issue because it's your repository. You're the boss. You do as you please.

 

Project / Development Branch

When you want a stable master branch that represents the official released code, and you have active development going on, then there's the possibility to create long living additional managed branches.

The development branch starts as a clone from the master.

You'd want to set up a policy for such a branch too, similar as the master branch.

Then developers will create feature branches based on that development branch, not the master.

Their process is the same as explained in the Feature Branch section, while they are developing inside that feature branch.

But once done, they create a pull request to the development branch. Not to the master branch.

When the admin approves the request, code is merged into the development / project branch and the feature branch is deleted. Job done.

The repository admin should not accept direct pushes from such a feature branch into master.

 

At release time, the release manager (or you if you are lonely) will create a pull request with the development / project branch changes to the master branch.

Once the repository admin accepts that request, this is the new released version.

 

 

You can have several managed development / project branches in a complex project.

Just keep in min that everyone needs to understand what branch is for what, who manages it and where the results should flow to.

My advise is to start simple. And if that simple approach works, don't make it more complex.

Only if you can't manage the contributions in a simple way, then add. See my last line in the Single Branch section for a similar advice.

 

 

In the next part I'll add an approach to allow bug fixes in the master branch. Managed, and with a solution to integrate them in the development branch.

Comments and critiques are very welcome. There are better approaches than mine.

 

 

 

 

*1: or doesn't matter - if you use Git's own mechanism to create patches and mail notifications to request merge.

That approach is not the subject of this post. I want to document the process with pull management.

 

*2: in open source projects, it's common to have everyone run their own fork, instead of allowing the contributors to create branches in your account.

Everything works similar as here. They can create pull requests from such a forked repository into (one of our) branches.

Advantages:

  • you don't have to create and manage users. And several of the suggested repository hosts have a limit on their free tier.
  • The contributor can have their own strategy and approach. You aren't impacted by how they manage the code.
    The only thing you see is a pull request, just like one from a local feature branch.

Some of the hosts have project / issue management to assist the discussion with the contributors.

 

Related Blog
Firmware Version Control with GitHub part 1: Branch Strategy for New Features
Firmware Version Control with GitHub part 2: Branch Strategy for Bug Fixes
Firmware Release with GitHub: Branch, Issue, Pull Request and Project support
Fix a Bug in Production with GitHub: Issue, Branch, Project and (Draft) Pull Request supported + Eclipse Git Plug-in
Break-Fix with GitHub: part two: push bug fixes to the development team
GIT course