Issues with branching and release strategy

[johnbillion]

A branching and release strategy was discussed and implemented in #165 and #190. I've identified several problems with this strategy from the point of view of a contributor to FAIR Connect:

1. This strategy results in a non-stable target branch for PRs. Every six weeks the target branch for PRs will change.
   • A contributor (new or old) who clones the repo or attempts to use the GitHub web UI to propose a change will end up both branching from and targeting the wrong branch. Requiring PRs to target a non-default branch is highly unusual.
   • All contributors will need to discover the name of the new target branch every six weeks, use it in all their branching commands, and find and select it as the target branch for each PR. This will be laborious and introduces the likelihood of making mistakes.
   • All in-progress PRs will need to be retargeted every six weeks.
   • PR authors without maintainer-level access do not have permission to retarget their own PRs. This means a PR gets blocked until a release manager retargets it to the new release branch.
   • GitHub will actually automatically retarget PRs onto the default branch when the release branch gets merged, so there will be at least two retargets in short succession on in-progress PRs.
   • The release version number is effectively chosen six weeks in advance. Probably fine for minor releases but it doesn't lend itself well to point releases or major releases.
2. The release branch -- instead of the development branch -- gets merged into main.
   • A change can therefore bypass QA by being merged into the release branch shortly before it gets merged into main.
   • In the context of the release workflow, the development branch should be the one that gets merged into main.
   • However, the role of the development branch is unclear. The documentation states that it acts as a staging ground, but that's only true during the short window after the release branch is merged into development and when it's merged to main. It's serving no different purpose to the release branch.
3. As far as I can tell, this branching strategy is novel.
   • That doesn't make it fundamentally problematic, but it does indicate that perhaps it's trying to do something that's better served by an existing and well-known branching strategy.
   • The "Release Isolation" principle heavily dissuades work being done that is not intended for the current release. This principle is better suited to structured teams working in well-defined sprints, not open source projects looking to encourage outside contribution.
   • Given the six-week cadence of releases of FAIR Connect I would be tempted to recommend the standard GitHub Flow which is basically just feature branches targeting the default branch. The default branch is either the release-ready main or a develop branch which gets merged into it for release, the latter enabling more straight-forward hotfix releases.

I appreciate the considerable time spent by others on the branch and release strategy. I think the current strategy is not the correct one.

Edit: I have corrected the cadence of the FAIR Connect plugin to every six weeks.

[cdils]

Thank you @johnbillion. I appreciate you understanding there was considerable conversation that went into the newly adopted branching strategy and, though it's not perfect, it's the one agreed upon for now.

That said, after going through the first Release Candidate (RC) release using this strategy for Fair Connect (v1.3.0-RC1), I want to note the following complications and questions as I think they're relevant to this issue:

1. Github auto-deleted the release_1.3.0 branch after I merged into development. This setting was considered acceptable/desired behavior for cleaning up unused branches, but had the consequence of:
   • Inadvertently closing PRs that were targeting release_1.3.0 (see example: Rearchitect Updater into a registry fair-plugin#428). This also has a domino-effect of closing dependent issues.
   • There is no way to re-open closed PR's against a deleted branch, causing additional contributor work and friction (or worse–drop off) from needing to re-open a PR against the new release branch
2. We need to document or automate when the new release branch is created (immediately following? allow time for dust to settle, which felt right for this first release tag following the new strategy, but maybe not necessary for future refined workflows?)
3. Fast following the release tag for 1.3.0-RC1, I wanted to submit a PR with changes to release documentation, but it's unclear if this should be done toward a new milestone branch (e.g., release/1.4.0) or other?

To summarize my thoughts:

1. Protecting main as the current stable release branch is the top priority and this new release branching strategy was introduced as a way to achieve that. I wholly agree with that being the main priority. ;)
2. The named release branches (vs a more general development branch) makes it more difficult to contribute for new and existing contributors. Specifically:
   • The burden would be on a contributor to discover the latest or relevant release branch.
   • PRs intended for a milestone and based against that release branch that get re-milestoned:
     • need to be re-based off the new milestone's release branch (that may not or may not have been created yet)
     • would be automatically closed if not rebased
   • Stale PRs against a deleted branch are automatically closed and contributions are lost.
   • PRs that are not closed intentionally trigger closed issues and project boards are falsely updated with "Done" tasks
3. We can put protections in place via GitHub automation and Release Manager responsibilities
   that alleviate some of these concerns, but that doesn't solve for part about making it harder for contributors to get their contributions in.

---

To clarify one bit from @johnbillion's original issue:

The release branch -- instead of the development branch -- gets merged into main.

The release branch is merged into development per currently documented release branching strategy-> https://github.com/fairpm/tsc/blob/main/process/release-branching.md

[johnbillion]

I've just observed another issue since 1.3.0-RC1 was released yesterday. There's no longer an active release branch and the main branch is yet to receive the changes from the release, so there is currently no way for a user to open a PR and target a useful branch. I am blocked from opening a new PR for #428 as the only branch I can target is development.

The release branch is merged into development per currently documented release branching strategy-> https://github.com/fairpm/tsc/blob/main/process/release-branching.md

Yeah. I disn't phrase it well, but the issue is that development should subsequently be merged into main instead of the release branch being merged into main. Otherwise you'll get branch divergence when main needs to be merged back up in to development ready for the next release, and there's still the opportunity for something in the release branch making it into main without ever having gone into development.

I'll repeat what I said in the issue description:

The "Release Isolation" principle heavily dissuades work being done that is not intended for the current release. This principle is better suited to structured teams working in well-defined sprints, not open source projects looking to encourage outside contribution.

[Ipstenu]

I have set up protections on branches so release_* branches will no longer be deleted. FWIW there was a button to 'undo delete' after it was merged to development, but it's easy to miss.

Fast following the release tag for 1.3.0-RC1, I wanted to submit a PR with changes to release documentation, but it's unclear if this should be done toward a new milestone branch (e.g., release/1.4.0) or other?

It should be done to release_1.3.0 if it's part of the existing release (which ... documentation should be I would think).

But making a release_1.4.0 the day we tag and release an RC for 1.3.0 is not a bad idea.

The "Release Isolation" principle heavily dissuades work being done that is not intended for the current release. This principle is better suited to structured teams working in well-defined sprints, not open source projects looking to encourage outside contribution.

John I fully agree, however the issue we had is that things were merged into main before they should be, because we only had ... main. By having a release isolation branch, and assuming it's not deleted anymore when we merge to dev (mea culpa, I thought I set that up but I blame the moving brain), we mitigate that somewhat.

And as it happens.... we DO have 'defined' sprints, or rather a defined window. What's done in 6 weeks goes into release X.

[Ipstenu]

Yeah. I disn't phrase it well, but the issue is that development should subsequently be merged into main instead of the release branch being merged into main. Otherwise you'll get branch divergence when main needs to be merged back up in to development ready for the next release, and there's still the opportunity for something in the release branch making it into main without ever having gone into development.

The worry I have here is that development may have more than just one release.

For example, while we work on 1.4.0, there's a bug and we release 1.3.1

Things that have passed 1.4.0 may already be in development, so it's now out of sync.

Honestly it's shitty no matter how I look at it, and I struggle to figure out a flow that is easy to follow and not going to land us where someone merged to main early and we broke things.

Given the six-week cadence of releases of FAIR Connect I would be tempted to recommend the standard GitHub Flow which is basically just feature branches targeting the default branch. The default branch is either the release-ready main or a develop branch which gets merged into it for release, the latter enabling more straight-forward hotfix releases.

We were kind of using that before and ended up with things in main :/

[afragen]

I do get that we decided on a branching strategy and we should give us some time to get used to it. That being said John's comments resonate with me.

On many other projects there is a persistent branch to make PRs against as well as a "release" branch. In our case main is our
"release" branch. Having non-persistent development branches prior to a code freeze seem to be a cause for concern/confusion.

Using a git-flow pattern we could have 2 persistent branches and create a temporary release_x.x branch at code freeze or for hot fixes, features, etc. Testing for the release would be frozen to the release_x.x branch and once the release is to happen this is merged into both of the persistent branches( main and development ).

All PRs are to development unless they are for bug fixes to the release_x.x branch after code freeze, or to feature branches. At code freeze, release_x.x is branched off of development.