Our GIT branching model

What do you want to see in Armagetron soon? Any new feature ideas? Let's ponder these ground breaking ideas...
Post Reply
User avatar
Z-Man
God & Project Admin
Posts: 11369
Joined: Sun Jan 23, 2005 6:01 pm
Location: Cologne
Contact:

Our GIT branching model

Post by Z-Man »

This is mostly a matter-of-fact description of how I used our git branches to handle the 0.2.9.0.(1) release, and I think it's a good model going forward. Apart from details, it's essentially git flow. I like to think of it as train tracks (choo chooo!):
tracks.png
At the bottom, you have the current development track. For the 0.2.9 releases, that's 'legacy_0.2.9', git flow calls it 'develop'. That's where all the hacking takes place, alpha builds come from there.
At certain times, you let the tracks diverge into further development and a track that leads upwards to the next release. We have one branch for that, 'beta_0.2.9', source of beta builds; we just merge from develop to beta when it's time to prepare a new release. In git flow, you have one release branch for each release doing the same job, branched off from develop.
Then we have the release branch, currently 'release_0.2.9', at the top. Every time the beta branch reaches a certain maturity, we merge fully from the beta branch to the release branch; from then on, until develop is merged to beta the next time, release and beta run parallel. Builds from the release branch are release candidates. Git flow does not give this stage a separate name, it's all on the release branch.
Lastly, on the release branch, we have tags (the train stations) that mark proper releases.
You can read the train tracks as a graph where time goes from left to right; the number of potential problems increases from top to bottom. Potential problems because while the development branch may not actually have more real problems than the release branch, it has more poorly tested changes.

Not shown in the track pickture: actual development mostly happens in feature branches that split from and merge with the develop track, and the release track has the possibility of hotfixes getting applied in pretty much the same way.

Having separate beta and release branches has the advantage (over git flow) that when doing builds, the CI system can determine what kind of build it's supposed to be doing based on the branch name.
Having just one release and beta branch that are recycled release cycle to release cycle has the advantage that users compiling their own builds from git can just tune to a single branch and stay there. It has the disadvantage that if a hotfix is needed for version 0.2.9.3, but the release branch is already getting ready to release 0.2.9.4, the hotfix has no place to go immediately. It's no biggie, you can either just ditch the hotfix for 0.2.9.3 and integrate it directly into 0.2.9.4 (ready to release soon, right?? Or why have you merged it already into the release branch?) or resurrect the state of the release branch at 0.2.9.3 into a new branch and work with that.

If you prefer, you can draw the picture differently in the features/potential problems space, this time with feature and hotfix branches:
track_graph.png
Dashed lines here signify full merges into the branch that is getting dashed, time is only visible as the arrows on the graph lines.
The development branch is at the bottom again. You care about advancing features there, while keeping the potential problems manageable. Not too high, but you also don't force them too low so you don't hinder progress too much.
Beta and release branches have the purpose of decreasing potential problems. They don't need to actually change to do that all of the time, they just need to be tested. They go upwards.

With that structure fixed, there are still some open parameters I've been mulling about:
- when do you merge from develop to beta?
- when do you merge from beta to develop?
- asked by sinewav, having me stumped for a bit: what branch/release series should testers work on, and what should they actually do?

I think they can now be answered:
When do you merge from beta to develop?
When you're reasonably sure you can release in one or two days. You don't want to linger post-merge, pre-tag too long because of the hotfix limitation mentioned above.

What branch/release series should testers work on?
Beta. The purpose of the beta branch is to reduce potential problems by testing. At every point of its life, the beta branch is useful to test on. Either it's on its way up in the two pictures above, or it runs parallel with the release branch or is identical to the previous release.

(*)

What should testers actually do?
Use the test version for their regular play, all of the time ideally. I don't think there can be a checklist for beta testing; in beta testing, you want to catch the case where we changed system A without thinking about an interaction with system B that now breaks system C.

(*, too)

When do you merge from develop to beta?
On Mondays. You don't want to spring fresh, relatively high risk code on daring testers who also use the test version in tournament play. Also, obviously not before the previous release is out, and there has to be some change since the previous release. Otherwise, no restrictions. I think for 0.2.9, we should just use our guts, and then when 0.4 is current, stick to a schedule. At fixed times, every two or three months sounds right to me. Every month might me too often for us. It's a bit of a PR decision; releases get announced and it helps to have at least one change worthy of a headline. Maybe even precisely one.

(*) There is also value in testing the alpha branch, but that's different. Alpha testing can focus on the things explicitly mentioned in the changelog, to verify that we did indeed fix and implement what we claimed. That any gameplay additions or changes make sense. You definitely don't want to use an alpha for a tournament. I say that, but then again, the servers are all running on alpha code :)

syllabear
Shutout Match Winner
Posts: 1015
Joined: Fri Oct 13, 2006 1:37 pm
Location: UK/HK

Re: Our GIT branching model

Post by syllabear »

Very informative post.

Do you therefore want us to be using the "beta" builds on steam? (options are alpha, beta, experimental and staging, I appreciate steam may not mean the same things with their terminology as you)

Also:

Image
The Halley's comet of Armagetron.
ps I'm not tokoyami

User avatar
Z-Man
God & Project Admin
Posts: 11369
Joined: Sun Jan 23, 2005 6:01 pm
Location: Cologne
Contact:

Re: Our GIT branching model

Post by Z-Man »

syllabear wrote:
Tue Sep 15, 2020 9:56 pm
Do you therefore want us to be using the "beta" builds on steam?
Yes! I still need to write that up on the download site... 'alpha' and 'beta' map directly to what was discussed above. 'staging' on Steam are release candidates, mostly, and also the final actual releases before they are copied to the default Steam branch (you can't have the CI push to the default branch directly). Both come from the release git branch. 'experimental' are currently builds from trunk/0.4.

Post Reply