docs/internal: unify historical package branches

[jeffomatic]

No description provided.

[dominic]

👍 from me. I'd be interested in bikeshedding on the branch names. Something like:

release-1.0
release-1.1

1.0-stable
1.1-stable

chain-1.0
chain-1.1

[jeffomatic]

Re: naming, I'm down for whatever. Among those choices, x.y-stable read the best to me.

[dominic]

I like that stable emphasizes that main isn't as well.

[kr]

On the topic of naming things and "say what you mean", the word "minor" sounds weird to me for our versioning scheme. Our releases like 1.1 or 1.2 are a pretty big deal. But that's beyond the scope of this PR.

[jeffomatic]

I just made an update recommending that we use chain-core-server-<major>.<minor>.0 as the branch point for these version branches.

There is a weird edge case if there are changes to other packages (such as the SDK) that precede the chain-core-server release tag and are slated for the next minor version. For example, if main somehow contains a Java SDK commit that is slated for 1.2 and precedes the chain-core-server-1.1.0 release tag. This is technically possible and would mess with our unified version branch, but I doubt it will ever happen.

[jeffomatic]

Also, re-constructing the 1.0-stable branch will take some historical spelunking, since we will probably have to backport various SDK and installer updates that landed after the most recent 1.0.x Chain Core release.

[kr]

There is a weird edge case …

Yeah we should make it a rule to avoid that situation. Like we should close the tree leading up to a (so-called) minor release 1.n and don't open the tree for n+1 development until everything is clear.

[dominic]

we should close the tree leading up to a (so-called) minor release

I've seen other repos branch early into 1.x-development or 1.x-candidate when their root branch is approaching a release to avoid this issue.

[kr]

I'm not sure what branching early buys us. We'll just have a tone of commits on the candidate branch and almost none on main during that period. If possible, I'd rather we do the stabilization work leading up to a release directly on main, rather than splitting our attention between the upcoming release and future development.

In other words, it's something I'd hope we would do as a team anyway even aside from all the branching mechanics. It's less confusing if we make sure not to begin future dev work until the release is out the door.