gitflow and branch naming conventions

[Kamil Paral]

> > If I understand you correctly, you would like 'master' to contain
> > more stable code than what is usual for a large number of existing
> > projects - broken code, incomplete features, failures to even
> > compile, etc. And that is a nice goal indeed. I think we can achieve
> > that either by: 1. strong development practices - feature branches,
> > commit reviews, continuous integration tests or by: 2. not bothering
> > with strong development practices and putting all dirty work into a
> > separate development branch (let's call it 'develop') that's going to
> > be broken most of the time. However, every time the code starts to
> > look better (it compiles, tests pass), we promote it to master.
> 
> 2. is not acceptable in any way, shape or form. The development branch
> needs to be usable almost all of the time and we should be deploying it
> to a dev system on a regular (every couple of days, bare minimum) basis.
> Regardless of what we call the different branches, the only place it's
> acceptable to have regularly broken code is in a feature branch.

I didn't mean that 2. would be suitable for us :-) I just wanted to say that even this would be an improvement for some projects out there in the wild which have their master broken most of the time.

> 
> > Of course 1. is better than 2., but it would be nice if those
> > aforementioned bad projects adopted at least approach 2. The result
> > is that people interested in bleeding edge code have working master,
> > and even if they send a patch against master and 'develop' is used
> > for the actual development instead, usually those two branches are
> > not that far apart.
> > 
> > Unfortunately, that's not what gitflow does. In gitflow, 'master'
> > means *the* stable, it means old code.
> 
> No, it means "production ready" code. While that is going to be older
> than whatever we're currently developing by definition, it's not like
> develop is rawhide to master's epel. It's a consistent place to get
> stable code from if you chose to deploy from git or are working on a
> bugfix against the currently released version that can't wait for the
> development branch to be ready for release.

If you see it like this - you want 'master' to mean 'production ready' (== only officially released versions) - then gitflow makes absolute sense.

> 
> > It's not continuously updated
> > from develop branch, it's updated only at releases. It's not the
> > branch you want to receive patches against.
> 
> Why not? If the fix is for a bug in master, wouldn't we want the patch
> against the released code instead of against code which hasn't been
> released yet?

It depends how much we would have re-factored the in-development code in the meantime. In general I would rather see more patches against development code than against stable code, it's easier for us to merge. But in most cases it should not matter much, right.

> 
> > And it's kind of
> > superficial anyway, because why would you check out a branch
> > containing only tagged commits? In git you can check out a commit
> > directly.
> 
> How would you integrate any changes to that commit without making an
> unholy mess of the repo or releasing it as a patch?

Exactly the same as in the original gitflow model - by using hotfixes branch. See the picture at [1].

Let's say you find a problem in tag 0.1. You create hotfixes/0.1 branch starting from commit 0.1. You fix the problem in one or more commits. Then you tag the last commit as 0.1.1 or 0.2, as you wish. Finally, you can delete hotfixes/0.1 branch, it's no longer necessary.

Then you discover problem in tag 0.1.1. You create hotfixes/0.1.1 branch starting from commit 0.1.1, fix the problem, tag the latest commit as 0.1.2, delete the branch.

Of course all those hotfixes get merged into your development branch as well. Everything is the same as in the picture. I was just trying to point out that the rightmost thick line connecting tags 0.1, 0.2, 1.0 and so on (a branch called master on the picture) is not necessary at all. The only "advantage" it has is that it allows you to do "git pull" to get the latest stable release instead of checking out a tag directly ('git tag' and 'git checkout <tag>'). 

However, since you don't agree with master referring to development code and you rather want master to refer to the latest stable code (something I haven't expected before), then yes, the original picture in the article makes sense in this case. If you intention is to offer people the latest stable code by default (when they open up our github/bitbucket page, they are shown master as the default branch), it all makes sense and the branch is needed. (That's not what Fedora Infra does, however, they display 'develop' branch as default for many of their repos; that defeats the purpose of the rename in the first place).

> 
> > I think this part of the workflow was created with some
> > older SVN-like systems in mind, not git.
> 
> This workflow would be insane in SVN, branching and merging are
> expensive and tend to be painful.
> 
> > So, in gitflow a 'master'
> > doesn't mean 'unbroken code', it means the most stable code you can
> > ever get.
> 
> Exactly - it's stable code. The methodology provides a clean and well
> defined way to make changes to both stuff that's been released and stuff
> that hasn't been released yet. I'm not saying that gitflow is the only
> answer or that there aren't other ways to manage branches, I just think
> that it's a good, relatively well-defined solution and I don't really
> have a better alternative.
> 
> > So, it depends what you want to have. If you would like 'master' to
> > mean 'unbroken/more stable code', I think gitflow fails to deliver
> > that. If you would like 'master' to mean 'you can't get any more
> > stable', then gitflow is perfect. But I really don't think that this
> > is a common understanding.
> 
> Well, gitflow or any branching strategy isn't a cure. It's simply a
> methodology that takes any guesswork out of where code should go or
> what's in various branches. Without discipline and good development
> practices, it's worse than useless because we'd have multiple branches
> with an unclear purpose instead of just one.
> 
> One of the biggest advantages I see in having a 'develop' branch is
> that new features don't have to come to a halt at release time. If we
> combined master and develop, new features can't be merged in once we
> start the pre-release process. How do you propose we do release
> branches without a separation between develop and master?

That's what the 'release' branches are for, see picture at [1]. It's like branching Fedora XX from Rawhide. You branch 'release/1.0' branch from your main development branch and you can work on both in parallel - stabilizing the release in the release branch and do more development in the development branch.

So, in my world, 'master' branch never stops and 'release/XX' branches are branched from it. In gitflow world, 'develop' branch never stops and 'release/XX' branches are branched from it. I don't see any major difference :-)

> 
> How would hotfixes work if we find critical bugs in released code
> when our development branch isn't ready for release? How would the
> gitflow tool be affected? Can it handle stable and development branches
> being the same?

Let me try to illustrate my changes a bit better :) See this:

http://i.imgur.com/dLMe9fM.png

or alternatively this:

http://i.imgur.com/MQ1Hpg3.png

I haven't suggested any other changes to the workflow, everything remains the same. All features stay intact. I just proposed to fix a logical inconsistency in branch naming (in my view).

> 
> > > That being said, I'm not completely against this idea if there are
> > > enough other folks who are +1. I'm still -1 on the idea but I could
> > > live with it :)
> > 
> > In that case it will depend on what others think (or if they voice
> > any opinion at all). Of course, I could live with the default gitflow
> > as well. I just simply find confusing and a bit irritating its choice
> > to rename traditional branch names for no apparent reason or benefit
> > (in my view). I can definitely cope with it, sure, I'll remember what
> > branch name to use. But I'm concerned about the passers-by and
> > potential bleeding-edge users/contributors. I see this as an
> > unnecessary bump on the road they need to hop over.
> 
> I'm not as worried, to be honest. We need to document our processes
> better but in a similar vein to what I said about github and making
> drive-by patches easier, if someone is not capable of looking at the
> readme or any other docs before writing a patch ... are we really that
> confident that any contributions would be useful and wanted? If
> reading the readme and typing 'git checkout develop' is too much work
> for testing, how likely is it that the same person would take the time
> to file a decent bug or send mail to the list?

I agree with you, people will need to read documentation anyway. The only thing I dislike is that we want to divert from the traditions that everyone knows. 'master' is traditionally used to mean the main development branch, or at least _a_ *development* branch. If we want to have a branch with just stable, released code, why wouldn't we call it 'stable' (or anything similar) instead of changing the meaning or 'master' and then using a different branch for the purposes of master?

But I don't think we should spend too much time on this. If you believe that we should go against the tide and have 'master' to mean something else, I'm fine with that. I simply did not expect that this is really your intention.

> 
> It'd be nice to hear some more opinions on this - especially
> from folks who will be regular contributors (don't make me call you out
> by name because I will resort to that if needed).

I think they are a bit discouraged by the long discussion and they don't want to wrap their brains around all those graphs and models. I'm not surprised, I did not expect to go into so much detail anyway, for me this was a trivial rename fix proposal. But apparently I wasn't able to describe properly how simple all of this is, and it evolved into such a complex monster issue :-) I'm fine with anything, really.