One of the things that David and I discussed last weekend was changing the way we use Git to be more effective with it. The model we were thinking about using (since it's so widespread) is Vincent Driessen's "Successful Branching Model", also known as "git-flow".

Basically this means that rather than at present where we do all our development in one master branch which is in a constant state of flux we will instead work in two separate branches. The master branch will now only hold released versions of the code and so following out that branch (the default) will mean that the code will always compile and will only change occasionally. We will introduce a separate branch called develop which will contain things being put together for the next release (and should still always build but this is less guaranteed). Any feature we are developing will branch off and then be merged into the develop branch when ready. When we want to release we will merge the changes from develop into master and tag a release.

For users there will be almost no change (except we will be doing actual releases more often) but for anyone working on a feature or something for PolyVox it means that we ask that you make your work a branch off develop before you share it with us. If you've already started work on a branch off master, you will be able to rebase your branch onto develop when the time comes.

However, we haven't yet switched over to this model and so I wanted to see people's thoughts on when we should switch. Theoretically, we could switch right this second and there would be no problems. We could have a changeover period (of a week or two) where, while technically we're working under the new model, anyone with changes currently based on master (like no-doubt David has) can push them as normal and we can then merge them into develop afterwards.

To assist with the new model, there's a git plugin called git-flow which works on all our supported platforms to allow you to do things like git flow feature start my-new-feature, git flow feature finish my-new-feature and git flow release start 0.2.

Any thoughts?

_________________
Matt Williams
Linux/CMake guy

Basically I think this is great. But can you clarify/confirm the following points about how this works?

Firstly, the branch we currently have on Gitorius will become known as the master branch. I assume the new 'develop' branch will also be kept on Gitorius because multiple people may want access to it. What about feature branches? Do the people who are working on these keep them locally (sharing their changes directly with each other) or do we create a branch on Gitorious for each feature we want to add? Perhaps this depends on how many people are working on each feature?

Secondly, what is the relationship between branches and clones? In Gitorious there are a number of 'Respository Clones' listed down the right hand side (milliams-polyvox, etc). My understanding is that the 'develop' branch will not appear here but will instead be part of the main repository. Any one who then clones the repository will then also be cloning any branches it contains. Is this correct, and if so is there a way to view the branches in Gitorious?



I think we should try to make the switch before the release, and then use this model from the release onwards. I can make the switch anytime as I donn't keep many changes locally (I just push them straight away, which is why we are changing the system). Freakazo and realazthat are the only users who I know might be affected, and they'll probably be pleased to see Git become a bit more stable.

On the repository on Gitorious we will indeed have the master and develop branches and any changes we make locally to either of those we can push to the server. As for feature branches; it depends. If it's just something that you're working on yourself and/or is only a quick change (2 or three commits-worth) then it's probably not worth sharing it. Just merge it to (or rebase it on) develop it locally and push the develop branch to Gitorious. For any larger branches that we might want to collaborate on (either just the two of us or other members of the community) then we should push those so that anyone cloning the Gitorious repo will also get a copy of that branch.

Yes, branches and clones in this case are different things. Any repo is essentially one tree of commits full of branches. Each of these branches will have a name (internally a branch is named by attaching a label to the tip of that branch) so the Gitorious main repo will have two names branches in it: master and develop. They will show up in the big grey box in the top-left of this page where it currently says "Branches: master". Look at the qtbase repo for an idea. When someone clones that repo to their computer with "git clone" they will get a full copy of the tree with all the branches within it. This is where Git and SVN branches are very different: in Git they're part of the main commit tree but in SVN they're just copies of the main tree in a separate directory.

The repository clones you see in the panel on the right are basically analogous to the local clone you have on your computer (the git terminology for any copy of the commit tree is a clone). When you and I are working we make a clone of the gitorious repo, make changes to our local clone and then push them back to the main repo. However, if someone who doesn't have push access to our repo wants to give us some code they can't do that. Gitorious basically provides us with a middle-man or staging area for other people's commits through the 'personal clones' feature. If user 'bob' wanted to give us a bug fix then they would make an account on Gitorious and make a 'personal clone' of our main repo (one click on the website). That clone is entirely stored on the Gitorious servers and would be called something like bobs-polyvox. bob would then make a local clone of bobs-polyvox on their computer with "git clone git@gitorious.org:~bob/polyvox/bobs-polyvox.git" and make any changes locally. When they wanted to give them to us they would push their local changes up to bobs-polyvox and then through the web interface request that we pull their changes and merge them into our main repo.

Alternatively one can pass around chains of commits by file (or email like the Linux kernel does it) which we can then push ourselves. Once the new Git model is up and running and we have the release out, I'll write some documentation on how people can contribute to PolyVox through Git.

In both bobs-polyvox and bob's local clone there would be both the master and develop branches (as well as any feature branches we've chosen to push to the main repo) and so bob would do all his changes as a sub branch off develop.

Ok so we'll make the switch before release and do the release through the git-flow model so that from that point on, everything is set up correctly. In many ways, the sooner the better so unless anyone objects (bear in mind it won't break anything in your local clone) I'll do it some time in the next week or two.

_________________
Matt Williams
Linux/CMake guy

Ok, great, I think I've got the idea. I do think this will make Git easier to work with and improve the quality of the code.

Yep, sounds good. I'll leave this to you and just do it whenever you find an appropriate time.

This all sounds good to me. Previously, I think I just cloned whatever revision was labeled stable. Now I'll just clone and merge to the "develop" branch, is that correct?. Until now, my git repo is totally separate from polyvox, and it just uses polyvox as a library, so I don't think this affects me that much, and furthermore since all my stuff is header only, the rest of polyvox should compile fine no matter. If we move to using git-flow, I might ask for a bit of help getting started if I run into trouble .

_________________
irc://irc.freenode.net/#polyvox

Well, your clone will contain the master and develop branches. Any changes you make should be done as branches off the develop branch, yes.If your code is fairly decoupled from PolyVox then you shouldn't have too much trouble adaping to any changes.

If you need any help when it comes to Git, I'd be happy to help.

_________________
Matt Williams
Linux/CMake guy