Branching & Release Scheme

[schrnz]

While #6 focuses on how to decide for a versioning scheme (e.g., semantic versioning), this issue focuses on the branching and release policy, hence what branches to create when, how to merge them, when to release, what can and should be automated etc.

Affected Projects

• ARTist
• art
• ArtistGui
• dexterous
• monkey-troop
• Codelib
• codelib-gen

[schrnz]

Migrating the discussion with @sweisgerber-dev here:

Your proposed Semantic Versioning (as git tags) along with the classic git-flow should solve all our problems? :)

• git-flow:
  • http://nvie.com/posts/a-successful-git-branching-model/
  • https://danielkummer.github.io/git-flow-cheatsheet/

[schrnz]

I looked into GitFlow and I have to admit that I share some of the critique towards the model (see here), such as the unnecessary develop branch and the fact that you should not only not rebase but in particular introduce artificial merge commits that bloat up the log.

Let me therefore add some new suggestions to the discussion:

• OneFlow: An effort to improve GitFlow in a straightforward way
• GitHub Flow: More focused on continuous delivery/release
• GitLab Flow: Seems to me like a version of GitHub Flow meant for software that delivers versioned artifacts instead of continuous updates (e.g., apps & libraries vs web apps)

Maybe an adapted version of one of the above models can fit our purpose.

Some opinionated remarks from my side:

• I do not think the idea of always squashing features to a single commit is a good idea for our project. Often, features are quite involved and consist of multiple logical units that should be represented by a commit each. Those can still be reverted but it might be useful to address them independently
• dropping the idea of single commits per feature implies deviating from the idea that each single commit in the master branch represents a stable build, so we might think about a dedicated notion for that. Do we want to have a stable branch or is it enough to just tag releases and those are considered stable by definition?
• putting an emphasis on creating feature branches and discuss & merge them in via pull requests is well supported in GitHub and works our pretty well until now
• GitHub Flow seems to be a little too focused on continuous delivery, so I would assume we might want to start from GitLab Flow and adapt it to our needs?

Comments are very welcome.

[sweisgerber-dev]

Well most of the critic to git-flow in the linked article is valid, with "being too complicated" leading the way.

I do not think the idea of always squashing features to a single commit is a good idea for our project. Often, features are quite involved and consist of multiple logical units that should be represented by a commit each. Those can still be reverted but it might be useful to address them independently

Yes, as long long as we can still squash when it makes sense, like e.g. eliminating multiple WIP/Backup commits when merging a feature branch to master, I agree with you. There are often scenarios where we wan't to keep separate commits.

dropping the idea of single commits per feature implies deviating from the idea that each single commit in the master branch represents a stable build, so we might think about a dedicated notion for that. Do we want to have a stable branch or is it enough to just tag releases and those are considered stable by definition?

I'm not yet decided if it should be "stable" or only be able to compile and execute in a potential buggy way.

GitHub Flow seems to be a little too focused on continuous delivery, so I would assume we might want to start from GitLab Flow and adapt it to our needs?

Yes, I agree with you here, that sound like a good alternative, perhaps mix it w/ OneFLow. Let's discuss this topic further in person and leave the results here later.

[schrnz]

@sweisgerber-dev and me discussed this for a while and I will share the results here to resolve this issue:

First off, the master branch is our current (somewhat) stable state. It successfully builds (if combined with the correct versions of other repos if needed) and does not contain half-baked features, untested bug fixes or the like. Since our projects are not suitable for continuous delivery, there is no auto-deploy or auto-publish for master.

When working on features, fixes or refactoring, we branch off master and name the branch accordingly (feature_, fix_, refactor_, ...). Those branches can be merged back into master with pull requests and in the best case after code reviews and if CI passed.

Releases are based on the master branch. Depending on whether we need to have extra commits for a release, we use one of two possibilities for our repos:

1. If we need to include changes for the release only (e.g., set a version number somewhere), we will branch off master with the naming scheme release_<version> and tag the last commit with v<version>. Having different naming schemes for tags and branches avoids ambiguity and unexpected behavior (not all git commands have the same resolution strategy when branch and tag names coincide). The release branch should never be changed again after the tag.
2. If we do not need to have additional commits for a release, i.e. a commit in master represents what we want to have as a release, we simply tag it with v<version>.

@sweisgerber-dev pls have a look again to check if I missed sth, but I think this should suffice for now.