Define a release cadence

[fmvilas]

Description

Currently, there's no information on what would be the next version. I don't even know myself, to be honest. Many people ask me when we'll release the next version of the spec and what version would it be. E.g., 2.0.1, 2.1.0, or maybe 3.0.0?

Therefore, to make sure we always set the right expectations, I propose we define a fixed release cadence. Below is my proposal but feel free to leave yours as well.

Release cadence proposal

• Continuous releases for patch versions. We should not be waiting to fix a typo, a wrong example, or something that doesn't change the spec but just corrects the specification text.
• 3 months cadence for minor and major versions. We set fixed dates for the next releases. People know exactly when a new version of the spec will be released. We release whatever we have. If what's being released has breaking changes, it's a major version, otherwise, it's a minor one. We work on long-lived branches that have the name of the target release month. E.g., 2021-05.

Related issues

#463

[aayushmau5]

I like these ideas. As for the release version, for major release we should go with 2.1.0 and minors or patches 2.0.1. Not really sure if it's in complaint with Semantic Versioning though.

Perhaps we can take some inspiration from https://semver.org/

[WaleedAshraf]

Related/Duplicate ticket: #463

[fmvilas]

Thanks, Waleed! Added it to the description. Although, please take into account this one is only about the cadence. As in how often should we be releasing new spec versions.

[fmvilas]

@aayushmau5 we're already following Semver :) This issue is about the release cadence.

[lornajane]

I suggest quarterly releases, it takes the pressure off because if something isn't quite ready or doesn't make the cut, I don't think anyone could be upset about waiting 12 weeks, but half a year can seem too long and cause us to wait for "just one more thing" .... forever. I also suggest the dates are set for mid quarter, so we avoid other end-of-quarter noise and would therefore release in February, May, August and November every year.

[fmvilas]

Totally agree, @lornajane. Changing my proposal to every quarter.

[derberg]

now when I'm trying to imagine the flow here I think it was not the best idea to move spec's JSON Schema away from spec repo. Now it will be hard to make PRs, and imho PR with change in the spec should also update JSON Schema if only possible of course. Why? because after merging to 2021-05-01 branch we should generate a release candidate artifact so others can play with it.

I also in general have a problem with cadence, fixed dates always bring stress and mistakes. You know how much I love sematic release and conventional commits. They support release candidates, you then have branch master and next and whenever you push to next then you out of the box get bumps with alpha suffix (something that needs deeper investigation). What I'm trying to say is, no cadence, but, new things go to next and we get immediately artifacts released (I think best would be to have https://github.com/asyncapi/asyncapi-node as part of this repo). Once artifacts are available, we can work on updating tooling (to define what is must-have, parser and converter? generator too?) and then we can actually release.

so it is not about fixed cadence, it is about continuous release + "cadence" for tooling.

1. merge to next
2. update tools asap
3. 🔄 improve next if issues spotted while working on tools
4. release both spec and tools

advantage? the community must focus on community tools to get the new version in place 💪🏼

now....I'm not fully into this idea as I didn't have time to think it through. It just popped in my head and decided to share

[jstoiko]

I would be cautious not to create a cadence that is too aggressive, at least for backward-incompatible major releases. I would not expect a specification to get such a fast cadence anyway, at least past the "1.0"/GA mark. AsyncAPI being at 2.0 now, there is an expectation that it is "mature" or "mature enough".

Tooling needs to catch-up each time a new version of the spec is released, minor or major. This means not only supporting the upcoming version of the spec but also making sure the previous versions of said spec are supported as well. A fast cadence may have the adverse effect of causing some tools to consciously decide not to support a particular version as by the time they get to it, it might almost be time to release a new version of the spec.

Also, end-users may start drafting their API definition using the latest version of the spec, but if by the time their tools supports that latest version, a new version of the spec is released, or worse, if as previously described said tool decides to "skip" that version, the end-user may have no other choice but to re-write that API definition altogether. This may cause some frustration.

[derberg]

Release cadence should not be limited by the risk that some users will not catch up with API definition update or vendors will not catch up with given version support.

There will always be users that are super happy with 1 version or just older versions, but this should not block those that want to be up to date. There are users that are happy with AsyncAPI 1.0 and users happy with Swagger 2.0 and users of old JSON Schema drafts and they do not need anything else. They should have converters in place that they can use to switch between versions and use the latest tools.

Doesn't matter if we do 3m, 6m, 12m cadence, there will still be people who will have issues even with 24m cadence. Users should get what they need when it is already available, not wait for some specific date. Only users that need some feature will need to have manuals and migration guides and release notes, the rest should just get tools in place, converters.

Example -> #458 why would Waleed (not only Waleed as we identified this is an important missing feature) need to wait for 3months or even more, for the minor release? why not adding it once we have all in place + core tooling is updated?

[WaleedAshraf]

I agree with not labeling the release as a fixed date. This can be a bit hard to manage.
We can say the first week of every quarter will be a new release. That will give enough wiggle room to the team to prepare the release.

[derberg]

You know what. I just took a challange and wanted to write down and alternative proposal basing on what I wrote in previous comment....but I failed. I think this is the best we can do now. 3months are great.

@fmvilas I would only suggest, as in my comment and the one from WaleedAshraf. We do not want to live in stress here and I propose branches like 2021-05 and not 2021-05-01 to set a month when we release but we do it in a nonstressful way.
Later in the process, we can have clear guidelines that in case of, for example 2021-05 we start organizing release the first day, check a checklist of things to do, like final fixes, communication, blog post, press release, and that nothing new comes into the spec. Something like this 🤔

[derberg]

@fmvilas since you gave me a 👍🏼 I assume you agree 😅
Can you then update description. To me, it looks like we have an agreement. We also waited for 1month for the feedback.

Sound to me like we can schedule first release 😄 My suggestion - we do not write process/release instruction upfront but while working on first release. And next suggestion - we do as small release as possible to not overcomplicate as it will be our first release like this, so definitely we should avoid breaking changes 😅

[fmvilas]

Alright, updated the description to set a release month instead of a release date. Absolutely agree we shouldn't try this new system with 3.0.0 😅

[fmvilas]

I just created the 2021-06-release branch in this repo and in the asyncapi-node one 🎉

[fmvilas]

BTW, I'm proposing June 2021 for our first release. That means the next ones will be in September, December, March, etc.

Are you ok with June?

[derberg]

recording of our public meeting where we talked about the release https://youtu.be/roiMTGhoBfo

[derberg]

as per the recording, my suggestion is the following (avoids holidays and December)

• June 2021
• September 2021
• January 2022
• April 2022
• June 2022
• September 2022
• January 2023
• April 2023
• June 2023

Which is still 4 times a year, not always every 3 months

[derberg]

As there were no objections here for over a week, the AsyncAPI 2.1 release is scheduled for June 2021

So far I captured below what needs to be done:

• we need to test current automation with all involved projects (parser-js -> where JS parser code is, asyncapi-node -> where JSON Schema of the spec is, spec -> where the spec itself is). The ultimate goal would be that when we have branch 2021-06-release in all of the, after merging of the PR we should produce proper artifact on NPM so it is easy for anyone to grab it and check it out. Example: we release @asyncapi/parser-2021-06-release.1 after merging 1st proposal, and after merging another one we produce @asyncapi/parser-2021-06-release.2
• we need to update all examples from the spec repo - if needed
• we need to work on a blog post with an announcement and explanation of what has changed
• we need to prepare social media communication
• @barbaño González I think it would make sense to check our current media partners and see with them if they can help out spread the news? maybe a dedicated press release?
• we need to check what are changes needed in other AsyncAPI tools (except for the parser and asyncapi-node mentioned above) to have a checklist of repos where the contribution is needed so we all can work on it as soon as possible.
• while we run first release, we need to draft a release process, so 2.2 or 3.0 is much simpler and anyone can help doing the release 🙏🏼

anything missing from the list? (there is also a thread in our slack about it. I will update list of task both, here and in the slack thread)

[magicmatatjahu]

react-component and html-template will have to (probably always) be updated with the new release. This is not a parser requirement, but we have to remember about it :)

[dalelane]

@derberg I'd like to get https://github.com/asyncapi/java-spring-template updated in time for the release so it supports the new SASL security schemes from #502

When do you think I'd need to submit a PR for that by so it's ready to be merged in time for the 2.1 release?

[derberg]

@dalelane is "as soon as possible" a good answer 😄 . Technically nothing is blocking you from working on the PR now. I think that if you open up a PR in May it should not be a problem to get it merged in June. Hard to bet on it as it is the first time we do such release 😄

[GeraldLoeffler]

i propose #531 for inclusion in AsyncAPI spec 2.1

[GeraldLoeffler]

i'll submit a PR for #514 in time for inclusion in AsyncAPI spec 2.1 and associated bindings specifications

[derberg]

one item more to do for release, maybe not a blocker for 2.1 but still something we need to fix is that any release on spec repo triggers push of latest spec to website repo so it is also published there in asyncapi.com

• we need to add some toggle to pick spec version from drop-down for folks to see old version
• make sure older versions are not indexed

in case someone wants to jump on this one, I’m all yours to create an issue and explain details

[aayushmau5]

@derberg Can I take that up?

[derberg]

@aayushmau5 that would be awesome. I'll update the existing issue with all details this week and then we can start from there.

[derberg]

@aayushmau5 ok, I think I captured all the requirements asyncapi/website#86 Feel free to ask whenever in doubts. @fmvilas you might need to double check if I did not miss anything

[fmvilas]

I think the only missing thing here is to write this down to a document and we can close this issue. Does anyone want to contribute it?

[derberg]

Progress on 2.1 release is tracked here #536

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

cadence like other release-related things are now officially documented here