Release branches layout and naming

[achamayou]

We currently cut 0.x releases from the master branch, but once we start releasing X.y, we will need to be able to patch and apply security fixes and create X.y + 1.

There are (at least) two possible layouts for this:

1. We create a release/X branch for each major release, and X.1, X.2 etc are tags on that branch. That branch has a CI + Daily configuration, so that all PRs against it are gated, and a build + full tests is run Daily to ensure nothing rots. Patches occur either by direct PR, or by cherry-picking changes from master, ideally via PRs as well.

2. We create a release/X.Y branch for each minor release, and tagging X.Y effectively "closes" the branch. Each release branch for a given major release is branched from the previous one, at the tag. CI applies to all release branches, on a wildcard basis. Daily should be modified to only run on the latest branch.

Open questions:

1. Do we have to at least one commit to each release/X.Y branch to disable Daily after a release?
2. Is there a way to "close" a branch for tagging, once the release has either been deco'ed (first case) or followed by a patch (second case).
3. Are there drawbacks to having a lot of branches?

[jumaffre]

Side note that I think is worth documenting here.

An interesting consequence of the off-master 0.17.2 release: as our cmake environment auto detects the latest CCF version with git describe --tags, any development work done off the tip of master would still report 0.17.1 (i.e. the latest release of CCF from master) as the latest CCF version.

I believe this auto detection mechanism is useful to keep going forward so we should probably think of not breaking it for our main development branch. A solution may be to tag the exact commit at which we branch off for a new release branch.

[achamayou]

That's a very good point, if we've just merged some changes to two release branches (say 1 and 2), would git describe --tags report something sensible?

[jumaffre]

I don't think so as git tags are just pointer to specific commits, which would be different once merged to main.

I've thought about this more and I believe it's fine to give up on this feature for the main development branch. Once we've branched for 1.0, I propose that we tag ccf-0.0.0 (or similar) on main and have that as the CCF version on the main branch, forever. This should also prevent us from releasing from main directly.

[achamayou]

This seems reasonable, I think we could even do it now? I don't know that it would prevent us from releasing from main though?

[jumaffre]

This seems reasonable, I think we could even do it now?

Yes.

I don't know that it would prevent us from releasing from main though?

I wasn't clear enough: on an accidental release from main, the artefacts (release, Python package) would be tagged 0.0.0, which would never be interpreted as a valid release. Of course, we would have other ways to prevent accidental releases from main (release pipeline not triggering from there, etc.).

[jumaffre]

This seems reasonable, I think we could even do it now?

We may actually want to wait until 1.0 as we may still pre-release from main before that.

[achamayou]

@jumaffre @eddyashton so to close on this, I suggest we go with option 1 for 1.0.

The plan for 1.0 would be to:

1. create a release-1 branch
2. cut a ccf-1.0 tag from it
3. Create a "CCF 1.x" job gating PRs to that branch and run daily.
4. Create a "Daily 1.x" job run daily only on that branch.
5. Set up strict branch protection on release-1

How does that sound?

If we decide we have a better way to do this by the time 2.0 comes around (~October), we can always change then.

[jumaffre]

Just to confirm a few points as they're not mentioned explicitly:

• Further 1.x releases would also be cut from the release-1 (release-1.x?) branch, but with a different tag (e.g. ccf-1.1).
• The branch is not expected to have day-to-day development work on it, only bug fixes.
• If a patch ccf-1.x.y for the ccf-1.x release is required, we'll need to branch off ccf-1.x, commit to that new branch and tag ccf-1.x.y from there.
• Changes to any branch should be merged (or cherry-picked) back to all branches the branch branched from (mouthful). For example, fixes on ccf-1.x.y should be merged back to ccf-1.x and main.

[letmaik]

I think there is some confusion on which versioning scheme is used. I think @achamayou has x.y in mind where x = new features, possibly backwards-incompatible, and x.y = bug fixes only, no new features, strictly backwards compatible. This deviates a bit from SemVer (which does allow new features within a major version) but that's ok. I would use release/1.x (where x is a literal "x") as branch naming scheme and create git tags (ccf-1.0) off of that.

[letmaik]

Follow-up... if you wanted to adhere to SemVer, you could also use x.y.z where y is always 0. It may be a bit clearer for outsiders that are used to this mental model (z = patches). In this case I would still use the same branch naming (release/1.x) and have tags like ccf-1.0.1.

[achamayou]

@letmaik sure, that's fine, I think being stricter than SemVer is still effectively compliant, but there is no downside. So for the avoidance of doubt:

ccf-1.0.0
ccf-1.0.1
ccf-1.0.2

All API-compatible, ccf-1.0.1 and ccf-1.0.1 only contain security patches or bugfixes. There is never a ccf-1.a.b where a > 0.

Any and all new features or breaking API changes must wait until ccf-2.0.0.

@jumaffre

Further 1.x releases would also be cut from the release-1 (release-1.x?) branch, but with a different tag (e.g. ccf-1.1).

Yes

The branch is not expected to have day-to-day development work on it, only bug fixes.

Exactly

If a patch ccf-1.x.y for the ccf-1.x release is required, we'll need to branch off ccf-1.x, commit to that new branch and tag ccf-1.x.y from there.

No, the branch strictly linear, patches are applied sequentially.

Changes to any branch should be merged (or cherry-picked) back to all branches the branch branched from (mouthful). For example, fixes on ccf-1.x.y should be merged back to ccf-1.x and main.

So no, because a branch only ever receives patches and nothing else.

In the hope of sparking clarity, here is a picture I made earlier:

[jumaffre]

If a patch ccf-1.x.y for the ccf-1.x release is required, we'll need to branch off ccf-1.x, commit to that new branch and tag ccf-1.x.y from there.

No, the branch strictly linear, patches are applied sequentially.

OK. So the expectation is that if a bug is found in the deployment in ccf-1.0 but ccf-1.1 and ccf-1.2 have been released since, the deployment should upgrade to ccf-1.3 (which contains the fix), rather than an hypothetical ccf-1.0.1. This makes perfect sense to me, and was useful to clarify.

Changes to any branch should be merged (or cherry-picked) back to all branches the branch branched from (mouthful). For example, fixes on ccf-1.x.y should be merged back to ccf-1.x and main.

So no, because a branch only ever receives patches and nothing else.

Hmm, I understand that the picture is actually simpler if we only have one depth of releases branches, but I believe fixes to a release branch should also be merged back to main, unless the bug has already been fixed there.