diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 000000000..5c2128447 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,11 @@ +# This file provides an overview of code owners in this repository. + +# Each line is a file pattern followed by one or more owners. +# The last matching pattern has the most precedence. +# For more details, read the following article on GitHub: https://help.github.com/articles/about-codeowners/. + +# The default owners +* @github-actions[bot] + +# The default owners are automatically added as reviewers when you open a pull request unless different owners are specified in the file. +/spec/asyncapi.md @fmvilas @derberg \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ad8aff46..512804f76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -170,7 +170,7 @@ must be a pull request. * Consensus the solution is preferred * Resolution of identified concerns and challenges * Precisely described with spec edits -* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/asyncapi-node) (might not be merged) +* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas) (might not be merged) A *proposal* becomes a *draft* when the set of problems or drawbacks have been fully considered and accepted or resolved, and the solution is deemed @@ -190,13 +190,13 @@ feature without explicit opt-in when possible. An RFC at the *accepted* stage is a completed solution. According to a spec Committer it is ready to be merged as-is into the spec document. The RFC is ready to be deployed in AsyncAPI libraries. An *accepted* RFC must be -implemented in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/asyncapi-node). +implemented in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas). *Entrance criteria:* * Consensus the solution is complete * Complete spec edits, including examples and prose -* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/asyncapi-node) (fully tested and merged or ready to merge) +* Compliant implementation in the [AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas) (fully tested and merged or ready to merge) A *draft* is *accepted* when the Committers have been convinced via implementations and tests that it appropriately handles all edge cases; that the @@ -234,7 +234,7 @@ mean it has to be the only person working on it though. They are a "person of reference" for a given RFC implementation and may or may not know about JS, relying on the help of other community members to implement the RFC on the -[AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/asyncapi-node). +[AsyncAPI JS Parser](https://www.github.com/asyncapi/parser-js) and the [AsyncAPI JSON Schema](https://github.com/asyncapi/spec-json-schemas). diff --git a/README.md b/README.md index cd3d0510c..aead1dc94 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ The latest draft specification can be found at [spec/asyncapi.md](./spec/asyncap * [Version 1.1.0](https://github.com/asyncapi/spec/blob/1.1.0/README.md) (deprecated) * [Version 1.0.0](https://github.com/asyncapi/spec/blob/1.0.0/README.md) (deprecated) -**Looking for the JSON Schema files?** Check out our [asyncapi-node](https://www.github.com/asyncapi/asyncapi-node) repo. +**Looking for the JSON Schema files?** Check out our [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas) repo. **Feel like contributing?** Check out our [community repo](https://www.github.com/asyncapi/community). diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md new file mode 100644 index 000000000..54173757a --- /dev/null +++ b/RELEASE_PROCESS.md @@ -0,0 +1,105 @@ +# Release Process of the AsyncAPI Specification + +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. + +## Release coordinator + +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. + +## Release cadence + +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. + +## Release phases + +### Kick off + +We start by creating release branches and a placeholder for release notes in the AsyncAPI Blog. + +#### Release branch + +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](CONTRIBUTING.md) for the specification requires changes in different projects to accept a proposal. The following repositories are involved: +- [spec](https://github.com/asyncapi/spec) where contributor works with the specification file, +- [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas) where contributor pushes changes to JSON Schema of the spec, +- [parser-js](https://github.com/asyncapi/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. + +This image shows part of the GitHub UI that shows how you can create a new branch using default branch as a base. + +#### Release notes + +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](https://github.com/asyncapi/website/) repository. Make sure the option `Allow edits and access to secrets by maintainers` is selected to enable support from maintainers. + +This image shows example pull request created in GitHub with release notes for AsyncAPI specification + +### Review and merge + +There are no step-by-step instructions to follow but a set of rules. + +#### Review + +- Everybody is invited to perform a review of proposals. The [contribution guide](CONTRIBUTING.md) 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](CODEOWNERS) must approve the pull request in all related repositories. + +#### Prerequisites for first feature merge + +- `spec` - Make sure all the official examples located in the repository use the new version of the specification, +- `spec-json-schemas` - Make sure changes are introduced in the new JSON Schema file, and they are exposed [here](https://github.com/asyncapi/spec-json-schemas/blob/master/index.js), +- `parser-js` - Make sure the list of supported AsyncAPI schema MIME types is extended with the new version [here](https://github.com/asyncapi/parser-js/blob/master/lib/asyncapiSchemaFormatParser.js#L43.) + +#### Merge + +- Merge can be done only by repository [CODEOWNERS](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 have `feat!: ` prefix, +- Pull request in the `parser-js` can be merged only if it uses the release candidate of `@asyncapi/specs` package produced after merge of a pull request in `spec-json-schemas`, +- First, changes are merged into the `spec` repository, then `spec-json-schemas` and then in `parser-js`. + +### Next steps + +- 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: + - [JavaScript Converter](https://github.com/asyncapi/converter-js/) + - [Playground](https://github.com/asyncapi/playground/) + - [React component](https://github.com/asyncapi/asyncapi-react/) + - [Markdown template](https://github.com/asyncapi/markdown-template) + +### Steps only after first feature merge + +- 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](https://github.com/asyncapi/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. + +#### Communication + +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. + +### Ship it! + +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 `spec` repository, then `spec-json-schemas` and at the end in `parser-js`. Like in the case of the merge of release candidates, a pull request in `parser-js` can be merged only if it uses the final release of the new `@asyncapi/specs` package. +- 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](https://github.com/asyncapi/spec/releases/tag/v2.1.0). +- 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 :smiley: diff --git a/assets/release_process/create_branch.png b/assets/release_process/create_branch.png new file mode 100644 index 000000000..8c1ae686e Binary files /dev/null and b/assets/release_process/create_branch.png differ diff --git a/assets/release_process/draft_pr.png b/assets/release_process/draft_pr.png new file mode 100644 index 000000000..0aa9b6f33 Binary files /dev/null and b/assets/release_process/draft_pr.png differ diff --git a/documents/review/EXAMPLE.md b/documents/review/EXAMPLE.md deleted file mode 100644 index 39f217a2e..000000000 --- a/documents/review/EXAMPLE.md +++ /dev/null @@ -1,37 +0,0 @@ -# AsyncAPI Review Document - -|Project name|Reviewers|Company|Spec version| -|------------|---------|-------|------------| -|Awesome project|Jack Johnson, John Jackson|ACME|v2.1.0| - -## Our goals with this project are to: - 1. Document a microservices architecture built with RabbitMQ. - 2. Create an SDK that will take care of connecting, sending, and receiving messages. - -## We expect to: - 1. Be able to define my queues and exchanges in AsyncAPI. - 2. Have everything we need to make the SDK work. - -## We found the following challenges or difficulties: - - - -### 1. The AMQP extension doesn't work for us. -The AMQP extension doesn't allow me to define my queues and exchanges. - -#### We think it can be solved by... -Improving the AMQP extension. - -#### Overall, we think this challenge/difficulty is... - * [ ] A "nice to have". - * [ ] A blocker for us to adopt this version of the spec. - * [x] Something that doesn't affect the specification. - - - -## Other thoughts? - -None. - ---- -_AsyncAPI Initiative — (website: [asyncapi.org](https://asyncapi.org), twitter: [@AsyncAPISpec](https://twitter.com/AsyncAPISpec))_ \ No newline at end of file diff --git a/documents/review/README.md b/documents/review/README.md deleted file mode 100644 index ad4fc17a5..000000000 --- a/documents/review/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Review Process - -This document describes the steps you should follow when reviewing a new version of AsyncAPI. - -## Steps - -1. Let the project director know that you want to start the review process. -2. Decide the project you're going to implement. It's always better if you choose a real world project related to your company or needs. -3. Download the [review template](./TEMPLATE.md). -4. Write down your goals and expectations. -5. Write down your feedback. -6. Share your feedback: - 1. [Create an issue](https://github.com/asyncapi/asyncapi/issues/new) and paste the review document, or; - 2. Send a message/email to the project director (if you're concerned about making it public) and attach the review document. - -## Template - -Download the [review template here](./TEMPLATE.md). - -## Example - -See an example of a [review document here](./EXAMPLE.md). diff --git a/documents/review/TEMPLATE.md b/documents/review/TEMPLATE.md deleted file mode 100644 index 7b5a90a70..000000000 --- a/documents/review/TEMPLATE.md +++ /dev/null @@ -1,37 +0,0 @@ -# AsyncAPI Review Document - -|Project name|Reviewers|Company|Spec version| -|------------|---------|-------|------------| -|{{PROJECT NAME}}|{{REVIEWER 1 NAME}}, {{REVIEWER 2 NAME}}|{{COMPANY}}|v2.1.0| - -## Our goals with this project are to: - 1. {{INSERT GOAL HERE}} - 2. {{INSERT GOAL HERE}} - -## We expect to: - 1. {{INSERT EXPECTATION}} - 2. {{INSERT EXPECTATION}} - -## We found the following challenges or difficulties: - - - -### 1. {{BRIEFLY DESCRIBE IT}} -{{EXPAND ON THE CHALLENGE OR DIFFICULTY YOU FOUND}} - -#### We think it can be solved by... -{{EXPLAIN ONE OR MORE POSSIBLE SOLUTIONS}} - -#### Overall, we think this challenge/difficulty is... - * [ ] A "nice to have". - * [ ] A blocker for us to adopt this version of the spec. - * [ ] Something that doesn't affect the specification. - - - -## Other thoughts? - -Please, let us know if there's something else you would like to tell us. - ---- -_AsyncAPI Initiative — (website: [asyncapi.org](https://asyncapi.org), twitter: [@AsyncAPISpec](https://twitter.com/AsyncAPISpec))_ \ No newline at end of file