This document is meant to explain the release process of the AsyncAPI specification. This document aims to describe all details of the process so that any member of the community can jump in and help coordinate.
AsyncAPI specification release involves not only spec release but also the release of AsyncAPI-maintained tools. Therefore it requires a single person called release coordinator to ensure the release goes well throughout all phases.
The release coordinator doesn't have to do all the work alone. The release coordinator needs to find the right people to do the work required for a given phase and engage as many people as needed.
AsyncAPI releases happen regularly in the following months:
- January
- April
- June
- September
Regular releases concern only major and minor releases. We do not decide up front if the next release is major or minor. This decision depends on the proposals for changes in the specification and how much they affect specification and tooling in a given release cycle.
Patch releases are automatically released and published.
We start by creating release branches and a placeholder for release notes in the AsyncAPI Blog.
At the beginning of the release cycle, we need to have a new release branch created in some repositories. The reason is that contribution guide for the specification requires changes in different projects to accept a proposal. The following repositories are involved:
- spec where contributor works with the specification file,
- spec-json-schemas where contributor pushes changes to JSON Schema of the spec,
- parser-js where contributor makes necessary changes in the JavaScript Parser.
Release branch must have a year and a month of the release as prefix: {YEAR_OF_RELEASE}-{MONTH_OF_RELEASE}-release. For example, a release created in September 2021 has a 2021-09-release release branch.
Once feature branches are created, there must be some initial configuration done in each repository.
Things to do in release branch as chore: changes:
spec- Make sure all the official examples located in the repository use the new version of the specification,spec-json-schemas- Create new JSON Schema file with new version name and expose it here here,parser-js- Make sure the list of supported AsyncAPI schema MIME types is extended with the new version here
Things to do in default branch and release branch as chore: changes:
- Set release branch name in prerelease configuration in some repos repositories:
Changes in the specification need to be well described. We need clear information on what has changed, why, and who contributed to the change. A regular changelog is not enough as it is not user-friendly. Every release must have release notes.
A draft pull request with release notes must be opened at the same time release branches are created. Work on release notes should be done on a feature-by-feature basis and not at the end of the release cycle. Cooperate with contributors. They should be able to provide input and also be allowed to work as release notes article co-authors.
In other words, once a feature is introduced in the release branch, make sure it is properly described in release notes.
The draft pull request must be opened against the Website repository. Make sure the option Allow edits and access to secrets by maintainers is selected to enable support from maintainers.
There are no step-by-step instructions to follow but a set of rules.
- Everybody is invited to perform a review of proposals. The contribution guide describes all requirements proposal needs to fulfill to reach
Stage 3: Accepted, - Pull request must be:
- labeled as an accepted proposal,
- created against the feature branch,
- created in all repositories specified in contribution guide,
- At least one user listed in CODEOWNERS must approve the pull request in all related repositories.
- Merge can be done only by repository CODEOWNERS,
- Every pull request must have a
feat:prefix that, after the merge, produces a release candidate with a minor version update. The major version must havefeat!:prefix, - Pull request in the
parser-jscan be merged only if it uses the release candidate of@asyncapi/specspackage produced after merge of a pull request inspec-json-schemas, - First, changes are merged into the
specrepository, thenspec-json-schemasand then inparser-js.
- Update previously created draft of release notes with information about the new feature. Collaborate closely with feature contributors,
- Notify maintainers of the following repositories that the first feature is merged and that release will be produced and therefore they need to start preparing for it:
- Open draft pull requests in all repositories required by the contribution guide. They should point from the release branch in the upstream to the master branch in the upstream,
- Update documentation in website to promote latest version of the specification. You can do it in the same pull request with release notes. No need to care for the specification markdown file on the Website. It updates automatically during work on release candidates and also after the final release.
Every release of the release candidate is automatically published on the AsyncAPI Twitter account and in the releases-dedicated Slack channel. Feel free to use other communication channels. Make sure that as many people as possible know about the change. Feel free to contact vendors upfront or other people that are interested in changes in the specification.
The release is scheduled for a given month, not a specific day. You do not have to wait until the last day of the month with the release. We release often, so it can be released in June if the change will not make it in April. Most important is the quality and not quantity of the features. The quality feature means it is properly delivered in as many tools as possible with very good documentation and examples.
- Release means merge of pull requests created from a release branch against the master branch. First, changes are merged into the
specrepository, thenspec-json-schemasand at the end inparser-js. Like in the case of the merge of release candidates, a pull request inparser-jscan be merged only if it uses the final release of the new@asyncapi/specspackage. - Make sure other maintainers from other projects under the AsyncAPI GitHub organization released their packages
- Merge release notes and once they are published, link them under the GitHub release for the specification, like here.
- Make sure proper communication is sent from all the official AsyncAPI social accounts and on Slack
Now relax as the next release is right behind the corner 😃