Implementing release branches to speed up release process

[jescalada]

Ever since we decided to scope GitProxy v2 to accommodate breaking changes (#1119, #1368), we've been slowly working towards getting a release out by the end of 2025. Although it's almost complete, the scope of the v2 release has kept expanding and the actual release got delayed by several months.

Another problem is that PRs that are meant for future releases like v2.1 (examples: #1332, #1139) haven't gotten reviewed outside the contributing organization, and PRs that aren't breaking (thus, perfectly fine to add to v2.1 instead) keep extending the scope of v2.0. Meanwhile, maintaining open PRs causes a great burden on contributors and maintainers alike, not to mention the risk of regressions when fixing large merge conflicts.

To prevent this from happening again, and to ease the process of maintaining old releases, I suggest we implement release branches to stabilize what goes into each release. We can make tags/releases for the latest v1 and v2 from their respective branches and keep main moving fast.

Since we're already close to getting v2 out, I suggest we merge the remaining PRs and make the rc5/final release as we've been doing previously. We could set up a release/1.20 for backporting bugfixes.

As for the release stabilization process, we might want to look into a voting system, or something like time-based releases to prevent scope creep from becoming a problem. Also, I'm not entirely sure which branch strategy is most appropriate here, would appreciate suggestions on this!

One more point to add is that GitProxy has been gaining traction lately thanks to getting activated by FINOS, giving us another reason to improve our release process so we can accommodate more contributors and maintainers.

What are your thoughts? @finos/git-proxy-maintainers

[dcoric]

I think this is a good idea. I’ve had the opportunity to work with both models, and in my experience, active development on a release branch, then merging to main when the release is finalized, fits sprint-based projects better.

For this project, I would go with this model:

1. main is for next-release development.
2. Create release/x.y at feature freeze.
3. Allow only bug fixes/cherry-picks into release/x.y.
4. Tag RCs and final release from release/x.y.
5. Keep a limited support policy (for example: latest major + previous major patch branch).
6. Use time-boxed releases, so unfinished features move to the next train instead of delaying release.

[c-rindi]

Looks like the link to "getting activated by FINOS" is broken.
Maybe this one? finos/community#361

[jescalada]

Fixed! Thanks for pointing that out.

[dave-gantenbein]

In my experience "cherry pick to release" is the better approach to prevent future regressions. In most cases this will prevent you from regressing by forgetting to merge a fix from the release branch back into main once the fire is put out. Not that the other way can't work, but it does require a bit more discipline.

[kriswest]

n.b. "cherry pick to release" is a lot simpler if the project is set to squash merge PRs by default (which we are not currently).

[dave-gantenbein]

Is there any drawback to changing that setting?

[kriswest]

Other well known (names for) release workflows are:

• Gitlabflow https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/
• GitFlow: https://about.gitlab.com/blog/what-is-gitflow/ - might now be know as GitHubFlow?

In and ideal (GitlabFlox) world, you get to release from main by just creating a release branch (as at present), then cherry pick PRs into release branches when you are backporting them into older release lines. As I said above, this is much easier if you squash merge the PRs.

[dave-gantenbein]

This is the way. :)

[andypols]

@jescalada, I’m glad you raised this. I think your frustration is justified, but I think the root cause was the decision to make v2 a defined release in the first place.

Before v2, we largely worked on main and released when the changes justified it. That was a simple process, and it seemed to support a reasonable release cadence.

Once we decided there would be a v2” the release stopped being a reflection of what was ready to ship and became a future target to build toward. That made it easy to keep pulling more work into the milestone — not just breaking changes, but also non-breaking improvements, cleanup, and follow-on work — because all of it could be justified as part of making v2 complete. I think that shift away from incremental releases and toward a future release plan is a big part of why we have not shipped since July.

From that perspective, I’m not convinced release branches address the root cause. If we return to shipping smaller, more frequent releases from main, release branches become much less important and can remain a secondary tool for stabilization or backports, rather than the center of the release process.

[jescalada]

Based on our discussion during the last community call (#1416), we decided to do proper release planning and sticking to the plan instead of extending releases indefinitely. To mitigate the delays, we could set a release cadence - anything that doesn't make it on time will be postponed to the next release. We could release every 2-3 months or whatever is most reasonable.

Does everybody agree on this solution?

---

I added an issue template we can use for planning releases and tracking PR status: #1452

Some of the boring stuff here can be automated using agents, hooks, etc. We could use agents to refresh the state of the listed PRs, notify us via Slack/email when a tracked item is Awaiting review or Ready to merge, and more. In other words, we can benefit from faster and more organized releases without the maintenance overhead 🙂