Use next branch for next minor releases

[smoya]

Context

We use semantic-release for releasing our software. That helps us to follow a standard procedure for the releases, which allows us to have the release process automated by scripts.

Semantic-release deploys, by default, the following branches:

• regular releases to the default distribution channel from the branch master
• regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (N.N.x or N.x.x or N.x with N being a number)
• regular releases to the next distribution channel from the branch next if it exists
• regular releases to the next-major distribution channel from the branch next-major if it exists
• prereleases to the beta distribution channel from the branch beta if it exists
• prereleases to the alpha distribution channel from the branch alpha if it exists

Source: https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches

Recently, we started using next-major branches, e.g. for the work related to 3.0.0 version of the spec (see https://github.com/asyncapi/spec/tree/next-major).

However, we don't use next for the regular minor releases. We do, instead, use {YEAR_OF_RELEASE}-{MONTH_OF_RELEASE}-release (Read https://github.com/asyncapi/spec/blob/master/RELEASE_PROCESS.md#kick-off).

Description

I suggest we create a next branch on the repositories and use it for minor releases.

My main motivation behind that is the fact we will always have a branch created in there (next) ready to be used, a branch contributors will always target by default unless they represent a BC, where next-major branch will be targeted. Less important, IMHO, is the fact that we would then be following the defaults of semantic-release, but also something that sums up.

PROS:

• Contributors will target always next, or next-major branch (unless patches, which will keep targeting master), so its easy for them to find the right branch to use as base.
• The need of asking contributors to change their target branch from master to the recently created release branch dissapears.
• We can configure default branch in GH to next. (Removing the 5th step in https://github.com/asyncapi/spec/pull/722/files#diff-f8db13a291483ecd3b9b3a658ef71578da20891791ddce676d767cd5174552dbR154).
• No need to add release branches into .releaserc files every time we start a release (e.g. https://github.com/asyncapi/spec/pull/681/files#diff-644a8fae29c8e8b6ad5405a2e66c718a3b27f2e12581b7c5e00396d32b3e5cde).
• Any other?

CONS:

• next branch name is not as clear as it can be 2022-04-release.
• Any other?

I would like to ask not only the Code Owners @fmvilas @derberg @dalelane but some randomly picked recent contributors as @char0n @KhudaDad414 @GeraldLoeffler @nictownsend @magicmatatjahu, even though everyone is invited to share their thoughts!

[dalelane]

We can configure default branch in GH to next. (Removing the 5th step in [... the release process])

This is a persuasive point to me. As you say, it removes the need to have to edit the branch names in package.json files for every release - so I like the simplification.

[fmvilas]

I'm sold. I'd just probably call it next-minor to avoid misunderstandings.

[derberg]

I have to say that be default I was against as in slack I could see only one motivator, which was consistency with semantic-releases

but, now, I see great improvement really:

• always the same next branch that contributing guide can mention, so specify to contributors that they should open PRs against this branch that is actually always there 💪🏼
• and yeah, no more need for manual creation of branches every few months and changing config in repos 🚀

I'm all ❤️ for it

I saw @fmvilas comment on next-minor. I'm with keeping it next as we agreed in the setup of release process that we never know what type of the release is the next one, even if few last releases were minor.

[smoya]

I'm with keeping it next

I'm in as well with next, also because it is the default name in semantic-release.

[smoya]

Release process for 2.4.0 version of the spec has been started, however there is no PR merged yet. Would you like to start doing it right now for this version? I'm happy to open PRs merging 2022-04-release into next branches. cc @dalelane @derberg @fmvilas

[fmvilas]

I'm with keeping it next as we agreed in the setup of release process that we never know what type of the release is the next one, even if few last releases were minor.

Yeah, you're right. It may happen that during a release we have only patches.

---

During the spec 3.0 meeting today, a new problem has been surfaced: are the next and next-major branches on the spec-json-schemas and parser-js repos to work on the version 3 of the spec? Or are they to work on their own next minor and major releases respectively? Apparently, there was a mix here. In parser-js, we want to have next-major because it's undergoing a major rewrite, therefore we want to concentrate all the PRs with breaking changes in a single branch, instead of releasing many major versions. That said, I thought next and next-major branches on those repos were to keep them in sync with the next and the next major version of the spec. Apparently, that wasn't the purpose.

So I'm here now suggesting that we use next-spec and next-major-spec in these repos. Just so they're not confused with their own release cycle.

I hope I made myself understandable 😅

[jonaslagoni]

So I'm here now suggesting that we use next-spec and next-major-spec in these repos. Just so they're not confused with their own release cycle.

I like this 👍

[derberg]

oh, good point about the naming, yeah next on parser will not be good, next-spec is ok. As for the major release, I'm not so sure. First of all we do not have anything about major releases in the current release process, as this is very individual and will be rare. So I do not think we need to agree on anything for it now + for 3.0 we already know that parser will also be bumped up with breaking changes

[smoya]

If i understand correctly, this is what we all agreed here so far:

• next-spec => replacement for 2022-xx-xx-release branches for releasing minor versions.
• next-major-spec => replacement for 2022-xx-xx-release for releasing major versions.

Shall we also keep next-major in repositories so we can work on major releases without having to wait for release branches to happen?
I would vote for a yes.
A really useful example is the work we are doing rewriting the Parser-JS to TypeScript asyncapi/parser-js#482.
Another example could be working on the next major release for the spec way in advance (like half a year) as we did for 3.0. We could start having some code in the next-major branch so it keeps being updated automatically, released by bots (prereleases) without the need of changing any .releaserc or package.json files.

WDYT?

[derberg]

next-spec - I'm all in for this one to have it always in the spec, schema and parser repos
next-major-spec - I'm all in for this one to have it for 3.0 related work, which will anyway continue next few months, but then we just remove it. As 4.0 will not come very soon I believe 😆

next-major I guess we can keep it for TS rewrite, but for 3.0 related work shouldn't it be done in next-major-spec?

[smoya]

next-major-spec - I'm all in for this one to have it for 3.0 related work, which will anyway continue next few months, but then we just remove it. As 4.0 will not come very soon I believe 😆

I would vote not to remove it. I don't think it hurts having that branch in there IMHO.

next-major I guess we can keep it for TS rewrite, but for 3.0 related work shouldn't it be done in next-major-spec?

next-major branches would be there just for major releases related to only the repository. Nothing to do with the spec, like the TS rewrite, the split out of JSON Schema definitions @jonaslagoni did, or any other breaking change not related with the spec directly.

As a summary, those branches will be there to remove friction for contributors so they feel free to start working on anything without having to ask for branches (ask for creating them or just to what branches their PR's should target).

[derberg]

I would vote not to remove it. I don't think it hurts having that branch in there IMHO.

it will quickly get outdated and will be less useful than it could. Of course, I mean after 3.0 release.
We do not auto-update branches that do not have PR's opened

[smoya]

it will quickly get outdated and will be less useful than it could.

I agree, it will. 👍

Will it make sense to always have that branch included in package.json semantic-release section so it will be just a matter of creating the branch to just have the prereleases working automatically in case we need it? Or we should just remove branch + mention in package.json semantic-release section as well? Happy with any solution.

[derberg]

I guess it makes sense to have it always by default in semantic-release config 👍🏼

[smoya]

After receiving all the feedback, this is what we agreed so far:

• To create the following branches and keep them permanently in all repositories involved in spec releases (as per today spec, spec-json-schemas, parser-js):
  • next-spec => replacement for 2022-xx-xx-release branches for releasing minor versions.
  • next-major-spec => replacement for 2022-xx-xx-release for releasing major versions.
• To include next-spec and next-major-spec branches into .releaserc or package.json files for being considered by semantic-release in all repositories involved in spec releases (as per today spec, spec-json-schemas, parser-js).
• To only create next-major branches on demand for those repositories that can have parallel developments that include major changes, that can be released independently from the spec; changes that only affect the repository itself and have nothing to do with major/minor spec releases. It can be all repositories except spec (if I'm not mistaken).
• To include next-major branches into .releaserc or package.json files for being considered by semantic-release in those repositories that can have parallel developments that include major changes, that can be released independently from the spec; changes that only affect the repository itself and have nothing to do with major/minor spec releases. It can be all repositories except spec (if I'm not mistaken). This can be done under demand or right now. Up to us.

Did I summarize 👍 or 👎 ? cc @dalelane @derberg @fmvilas @jonaslagoni

If we agree, I will add this into the RELEASE_PROCESS.md doc.

[smoya]

To include next-spec and next-major-spec branches into .releaserc or package.json files for being considered by semantic-release in all repositories involved in spec releases (as per today spec, spec-json-schemas, parser-js).

After releasing 2.4, I will work on this so I can remove the mentions to 2022-04-release and instead add next-spec and next-major-spec.

[smoya]

I created a PR updating the RELEASE_PROCESS.md + changing .releaserc file of the spec repository: #785

[smoya]

The following issues asking Code Owners to create those branches have been created:

• spec: Create next-spec and next-major-spec branches #786
• spec-json-schemas: Create next-spec and next-major-spec branches spec-json-schemas#214
• parser-js: Create next-spec and next-major-spec branches parser-js#545

[smoya]

The following PR has been created updating package.json to reflect the new branch strategy:

• spec-json-schemas: ci(release): use new branch naming strategy spec-json-schemas#215
• parser-js: ci(release): use new branch naming strategy parser-js#546

For the spec repo, the same PR that contains the changes for the RELEASE_PROCESS.md contains the change, but this time in the .releaserc file: #785

[smoya]

All the tasks and PRs related to this issue have been done or merged. Closing this issue.