Improving the development workflow: A Proposal

[Cadair]

Hello everyone,

A bit of background: I spend a chunk of time reviewing PRs to this repo, and generally trying to help out with my software development experience. The way new features get developed at the moment tends to be a little hap-hazard and generally tends to make my life as a reviewer harder. I also think that it isn't particularly clear to people installing from git what's going on or how to test new things.

This project has become very collaborative and we are now getting more contributors and we should agree upon and then document a development workflow to help everyone out.

Proposal

My proposal is basically that we adopt what is commonly referred to as git-flow where all the development happens on a branch named develop and the master [1] branch just holds the commits for the latest release, so people who install from git (using something like git clone https://... --branch master) get the latest release, but they can swap to development if they want.

The upshot of this would be the following:

• We no longer create development branches upstream (unless it's a really really large feature), all changes to develop should be made by pull request from a fork.
• We encourage pull requests which are smaller, even though a large feature may be spread out over many pull requests. (We should strive to keep develop functioning at all times though)
• We document (and maybe even automate 🙀 ) a release process which updates master.
• We (well @jekhokie ) changes the default git branch from master to develop so all PRs are opened against that by default.
• We change the documentation to encourage users to clone the master branch not develop.

[1] We might want to take this opportunity to rename our master branch to main as that's rapidly becoming the more common name for it.

[dom-robinson]

I'm all for this.

A quick 'how to' would make sense: so example git command sequences for

• those that want stable release
• those that want to checkout develop / latest
• those that want to 'contribute'

[MihajloPi]

I totally agree. There are currently too many branches being developed at the moment and it is really confusing.

[Cadair]

@dom-robinson @colinluthier Are you two ok with making all future branches on your forks and not this repo, as you do at the moment?

I will write up some docs.

[colinluthier]

Yes, I think that is best. I know how to do a PR from my fork but I have a hard time switching Repos for testing.

[Cadair]

I shall document that as well, because when configured correctly it's no harder than switching branches :)