Branching model - GitFlow vs github-flow, gitlab-flow?

[BurtHarris]

@sharwell, Sorry if this is old-hat for you, I still feel like I'm playing catch-up on Git and related techniques. Are you familiar with this? Lets discuss! @mike-lischke @fdeitelhoff your input is invited too.

I've been looking for a Git based branching model like the one I've used with Perforce/SourceDepot. I thought I had found found one in Vincent Driessen's branching model, and scripts for implementing it known as GitFlow. It looks like the original repro for GitFlow tools went dorment in 2012, and there is some fragmentation of forks.

Digging some into tools/scripts for implementing this, it seems there are some simpler alternatives based on potentially valid criticism of the original git-flow including github-flow and gitlab-flow. My initial read of these later two is that they are more focused on a "live-site" model rather than traditional "product" model, and that antlr4ts is really more of a "product", in that we may in the future need to support more than one version at once.

git-flow

[fdeitelhoff]

I'm using git-flow together with GitKraken. This tool has a nice integration if git-flow and I'm happy with it.

[sharwell]

Git in general is hard enough for the average contributor to understand already. To me and in the context of this project, git-flow doesn't solve any problem that it doesn't also make up (meaning it doesn't provide any advantage over the current workflow). On the other hand, it introduces substantial complexity which makes it harder for people to participate in the project.

[BurtHarris]

@sharwell as I see it, the problem I'm trying to address is that Git doesn't define a workflow. It's starkly unopinionated on how branching should be used leaving room for discrepancies between contributors. I think that's part of the reason Git is hard for the to understand, by itself its too flexible!

For example, how should branching tie into the release process. When does the package.js version number get incremented, and to what? That's the sort of thing I think we've got a lack of well-defined process on. For 'average' people, this isn't a concern, but for 'releasers' it is. The only things I think the average contributor would need to know about GitFlow are that:

• the master branch is reserved for released code, so only 'releasers' can commit to master. The latest code on master should generally correspond to the latest released version of the package.

• the develop branch is where day-to-day development goes on. Any pull requests the average contributor submits should branch from, and merge to develop. While we strive to keep develop buildable and passing all unit tests, it's not necessarily stable. Package.json version numbers in the develop branch will always be suffixed by -develop.

GitFlow tools should add automation to the release branch process, and for NPM packages like ours, can tie into tools like npm version and npm publish commands. They should not be needed by the 'average' contributor.

[sharwell]

When does the package.js version number get incremented

It gets incremented in the same commit which gets tagged for release, and the -dev suffix is removed or changed to a different pre-release indicator. The next commit changes the version number back to having the -dev or -SNAPSHOT suffix to indicate that the commit is no longer a release commit.

to what?

At this point it doesn't really matter as long as the major version is 0. Eventually it doesn't matter provided semantic versioning constraints are met.

the master branch is reserved for released code

This is not standard practice on GitHub. The master branch is what you are thinking of as the develop branch. If a special branch is needed for maintenance purposes, it can be created for that purpose at the time it becomes relevant, but users don't need to think about it.

For an example, take a look at the history of the DotNetAnalyzers/StyleCopAnalyzers repository. All work is done in the master branch, but we kept a stabilization branch in the event we need to create a servicing release for the last stable release (which occurred one time in 18 months).

[mike-lischke]

In my team we followed the git-flow approach to some extend and it worked well for us. However, it's not so special as it may sound. After all you always branch for new features (it's cheap in git so you do this even for smaller changes) and you have your working branch as usual. The only thing where processes differ is whether you use ˋmasterˋ for that or another branch (ˋdevelopˋ here). For quite some time we used a ˋdevelopˋ branch and merged to master only after a release, but since we want to work more like the MySQL server team does and since ˋmasterˋ is barely used in this model, we stopped using ˋdevelopˋ and now push directly to master. This requires however an OK from QA before we are allowed to do that, which in turn requires proper specification (using our workflow system) arch review, code review and final approval ( for larger work even product management has a voice). Personally I believe that an additional work branch is rather useless. Properly tag your releases (and or milestones) and you can quickly go back to an earlier release by checking out a specific revision.

Contributors should of course use an own branch for their pull request (not master), so they are not blocked when a PR is not accepted immediately and they want to do another PR. If you want to apply at least some QA in the antrl4ts branch you can ask previous contributors to do a code review before merging a PR.

[BurtHarris]

Thanks @mike-lischke. I think separating master from develop is primarily for the benefit of someone playing a casual observer role on the repository, rather than a real contributor. For the observer, the master branch is the one most likely of interest, it gives them the highest chance of getting source code that matches up with a package they've installed from https://npmjs.com rather that vNext still in development, without needing to know about tags etc.