Use release branching

[agjohnson]

Every time we do a release, we freeze the code base and halt merging of pull requests. It seems we might benefit from adding release branches for past releases, so that we can unblock development and have a known branch to backport changes to if ever necessary.

I'd suggest something like:

• We branch releases/0.5 from the last 0.5.2 tag
• We branch releases/1.0 from the 1.0.0rc1 tag
• master branch version becomes 1.1.0dev1, we can merge PRs for 1.1
• Any fixes needed for 1.0 are applied to master and cherry-picked to releases/1.0

cc @readthedocs/theme

[jessetan]

Sounds good, althouh I'd suggest to use something like releases/1.0.x or versions/1.0.x for the branch name so it is easier to disambiguate beween a tagged 1.0.0 release which you can check out and use, and a branch which is not actually released and may be more unstable.

[agjohnson]

Great point. We've tried a similar pattern in other repos and never really found a pattern that stuck, so I'm not super familiar with great patterns here.

Is releases/1.x too broad? Branches like releases/1.0.x definitely make sense if not, but it would be nice to limit the number of extra branches if possible. I don't see us backporting fixes to both a 1.0 and 1.1 separately ever, so releases/1.x might be enough really.

[nienn]

The GitFlow pattern by Vincent Driessen might be worth considering here. It's widely tested and has some great pointers on dealing with semantic versioning.

It uses one additional branch, the develop. Development is made through feature branches that continuously merge back into develop (instead of main). The main branch is updated only by release branches or hotfixes.

GitFlow Workflow

Illustration from Atlassian Gitflow Workflow

[agjohnson]

We probably wouldn't deviate too far from all of our other repositories, but the names there can translate to a similar pattern.

That is, we might be able to develop on master and use a singular releases branch instead of multiple. This doesn't give a great pattern for backporting changes, if that is important.

Perhaps we could start with a middle ground and use release or releases/all (all or anything similar here because we probably also want releases/1.1 at some point, and releases would conflict with nested branches).

Backporting changes is probably a remote, secondary concern.

[jessetan]

Is releases/1.x too broad? Branches like releases/1.0.x definitely make sense if not, but it would be nice to limit the number of extra branches if possible.

I don't think releases/1.x is too broad, we could use that. My main point is there should be a .x suffix somewhere to distinguish fram a tagged release.

[agjohnson]

Yeah, that definitely makes a lot of sense. I can put up a PR or two and hopefully unblock 1.1 development here.