[improve][doc] Release policy and matrix

contribute/release-policy.md

@@ -0,0 +1,89 @@
+---
+id: release-policy
+title: Release policy
+---
+
+## Release semantics
+
+The Pulsar project follows a variant of Semantic Versioning (semver), which replacing `major.minor.patch` with `LTS.feature.patch`.
+
+Concretely, existing releases can expect patches for bugs and security vulnerabilities. New features will target to feature releases. A "major" version bump will not carry any special meaning in terms of "big features" included in the release or breaking API changes. Instead, it would simply signal a new long-term support (LTS) release.
+
+For example,
+
+* 2.10.0 is a feature release;
+* 2.10.1 is a patch release;
+* 2.11.0 is a feature release;
+* 3.0.0 is the first LTS release;
+* 3.0.1 is a patch release of the LTS release;
+* 3.1.0 is a feature release;
+* 3.2.0 is a feature release;
+* 3.2.1 is a patch release;
+* 4.0.0 is an LTS release.
+
+## Compatibility between releases
+
+When upgrading an existing cluster, it is important to upgrade components linearly.
+
+Before 3.0, upgrade should be done linearly through each feature version. For example, when upgrading from 2.8 to 2.10, it is important to upgrade to 2.9 before going to 2.10.
+
+Starting from 3.0, additionally, live upgrade/downgrade between one LTS and the next one is guaranteed. For example,
+
+* 3.0 -> 4.0 -> 3.0 is OK;
+* 3.2 -> 4.0 -> 3.2 is OK;
+* 3.2 -> 4.4 -> 3.2 is OK;
+* 3.2 -> 5.0 is _not_ OK.
+
+## Release frequency and support expectation
+
+|                 | Release frequency | Active Support | Security Support |
+|-----------------|-------------------|----------------|------------------|
+| LTS release     | Every 18 months   | 24 months      | 36 months        |
+| Feature release | Every 3 months    | 6 months       | 6 months         |
+| Patch release   | When it is ready  | N/A            | N/A              |
+
+This can be translated into:
+
+* The last 2 LTS releases and the last 2 feature releases are supported.
+* Security patches are provided for the past 3 LTS releases and 2 feature releases
+
+Therefore, users can choose between stay in an LTS release until they are ready to jump into the next LTS, or try the latest releases which contains required features.
+
+## Supported Versions
+
+````mdx-code-block
+import SupportedVersionsTable from "@site/src/components/SupportedVersionsTable";
+
+<SupportedVersionsTable />
+````
+
+## Release cycles
+
+Generally, one committer shall volunteer as the release manager (RM) for a specific release.
+
+For feature releases and LTS releases, the last 3 weeks of the release cycle will be marked as a code-freeze period. The RM will branch off from master, and the RM is also responsible for selecting the changes that will be cherry-picked in the release branch.
+
+From the code-freeze point, to minimize the risk of delaying the release, only bug fixes involving a regression of behavior compared to a previous release should be allowed. Occasional exceptions will be possible after higher scrutiny of the change.
+
+1. At the moment of the code freeze, the RM will start preparing a release candidate (RC) following the [release process](release-process.md). Committers, contributors, and users will [test this RC](validate-release-candidate.md) to detect issues as early as possible. (A formal vote by the PMC will not be required at this stage, though any disagreement should be sent out ASAP).
+2. After 1 week, if there are any changes, the RM will provide a new RC release that the community will test again.
+3. After 1 more week, if there are any changes, a third RC will be prepared, and this will be submitted to vote to the PMC. Otherwise, the vote will be held on an earlier RC if no issues are found.
+4. The last 1 week will be used for the voting process and for updating Pulsar website and the blog post announcing the release, which should (hopefully) happen on the scheduled day.
+
+For patch releases, the process is the same while there is no code-freeze period and strict timeline. Basically, patch release is out "when it is ready".
+
+:::note
+
+For example, the next release of Pulsar is 3.0.0, and it has the planned timeline as:
+
+* 2023-04-11 - RC-1
+* 2023-04-18 - RC-2
+* 2023-04-25 - RC-3
+* 2023-05-02 - Announce 3.0 Release
+
+:::
+
+## Related PIPs
+
+* [PIP-47: A Time-Based Release Plan](https://github.com/apache/pulsar/wiki/PIP-47%3A-Time-Based-Release-Plan)
+* [PIP-175: Extend time based release process](https://github.com/apache/pulsar/issues/15966)

contribute/release-process.md

@@ -5,18 +5,18 @@ title: Release process
 
 This page contains instructions for Pulsar committers on how to perform a release.
 
-The term major/minor releases used throughout this document is defined as follows:
+The term feature/patch releases used throughout this document is defined as follows:
 
-* Major releases refer to feature releases, such as 2.10.0, 2.11.0, and so on.
-* Minor releases refer to bug-fix releases, such as 2.10.1, 2.10.2, and so on.
+* Feature releases contain 2.10.0, 2.11.0, 3.0.0, and so on.
+* Patch releases refer to bug-fix releases, such as 2.10.1, 2.10.2, and so on.
 
 ## Preparation
 
 Open a discussion on dev@pulsar.apache.org to notify others that you volunteer to be the release manager of a specific release. If there are no disagreements, you can start the release process.
 
-For major releases, you should create a new branch named `branch-X.Y` once all PRs with the X.Y.0 milestone are merged. If some PRs with the X.Y.0 milestone are still working in progress and might take much time to complete, you can move them to the next milestone if they are not important. In this case, you'd better notify the author in the PR.
+For feature releases, you should create a new branch named `branch-X.Y` once all PRs with the X.Y.0 milestone are merged. If some PRs with the X.Y.0 milestone are still working in progress and might take much time to complete, you can move them to the next milestone if they are not important. In this case, you'd better notify the author in the PR.
 
-For minor releases, if there are no disagreements, you should cherry-pick all merged PRs labeled with `release/X.Y.Z` into `branch-X.Y`. After these PRs are cherry-picked, you should add the `cherry-picked/branch-X.Y` labels.
+For patch releases, if there are no disagreements, you should cherry-pick all merged PRs labeled with `release/X.Y.Z` into `branch-X.Y`. After these PRs are cherry-picked, you should add the `cherry-picked/branch-X.Y` labels.
 
 Sometimes some PRs cannot be cherry-picked cleanly, you might need to create a separate PR and move the `release/X.Y.Z` label from the original PR to it. In this case, you can ask the author to help create the new PR.
 
@@ -46,7 +46,7 @@ Also, you need to **clean up the bookkeeper's local compiled** to make sure the
 
 We are going to create a branch from `master` to `branch-v2.X` where the tag will be generated and where new fixes will be applied as part of the maintenance for the release.
 
-The branch needs only to be created for major releases, and not for minor releases like `2.3.1`. For minor releases, go to the next step.
+The branch needs only to be created for feature releases, and not for patch releases like `2.3.1`. For patch releases, go to the next step.
 
 For example, when you create the `v2.3.0` release, the branch `branch-2.3` will be created; but for `v2.3.1`, we
 keep using the old `branch-2.3`.
@@ -71,8 +71,6 @@ If you created a new branch, update the [CI - OWASP Dependency Check](https://gi
 
 Note that you should also stop the workflow for previous Pulsar versions that are EOL.
 
-Also, if you created a new branch, please update the "Supported Versions" table on the [version policy](version-policy.md) page. This table is for support timelines based on when minor releases take place.
-
 ### Update project version and tag
 
 During the release process, you are going to initially create "candidate" tags, that after verification and approval will get promoted to the "real" final tag.
@@ -103,7 +101,7 @@ git push origin branch-2.X
 git push origin v2.X.0-candidate-1
 ```
 
-For minor releases, the tag is like `2.3.1`.
+For patch releases, the tag is like `2.3.1`.
 
 ### Build release artifacts
 
@@ -349,7 +347,7 @@ If you don't have the permission, you can ask someone with access to apachepulsa
 
 :::caution
 
-This step can be skipped if the major version number is not the latest.
+This step is for the latest release only.
 
 :::
 
@@ -452,7 +450,7 @@ Read more on the manual of [pytools](https://github.com/apache/pulsar-site/tree/
 
 :::caution
 
-This step is for major releases only, unless you're sure that significant Javadoc fixes are made against the minor release.
+This step is for feature releases only, unless you're sure that significant Javadoc fixes are made against the patch release.
 
 :::
 
@@ -476,7 +474,7 @@ Read more on the manual of [pytools](https://github.com/apache/pulsar-site/tree/
 
 :::caution
 
-This step is for major releases only, unless you're sure that significant reference fixes are made against the minor release.
+This step is for feature releases only, unless you're sure that significant reference fixes are made against the patch release.
 
 :::
 
@@ -497,7 +495,7 @@ Read more on the manual of [pytools](https://github.com/apache/pulsar-site/tree/
 
 :::caution
 
-This step is for major releases only, unless you're sure that significant doc fixes are made against the minor release.
+This step is for feature releases only, unless you're sure that significant doc fixes are made against the patch release.
 
 :::
 
@@ -517,7 +515,7 @@ Read more on the manual of [pytools](https://github.com/apache/pulsar-site/tree/
 
 :::caution
 
-This step is for major releases only, unless you're sure that significant doc fixes are made against the minor release.
+This step is for feature releases only, unless you're sure that significant doc fixes are made against the patch release.
 
 :::
 
@@ -553,7 +551,7 @@ For every release, you should add a `<release-version>` entry to the correspondi
 
 :::caution
 
-The following steps are for major releases only.
+The following steps are for feature releases only.
 
 :::
 
@@ -631,7 +629,7 @@ svn rm https://dist.apache.org/repos/dist/release/pulsar/pulsar-2.Y.0
 
 :::caution
 
-This step is for major releases only.
+This step is for feature releases only.
 
 :::
 

package.json

@@ -39,6 +39,7 @@
     "lodash": "^4.17.21",
     "md-2-json": "^2.0.0",
     "mkdirp": "^1.0.4",
+    "moment": "^2.29.4",
     "node-static": "^0.7.11",
     "npm": "^8.1.3",
     "prism-react-renderer": "^1.2.1",
@@ -49,6 +50,7 @@
     "react-svg": "^14.1.13",
     "remark-linkify-regex": "^1.0.0",
     "replace-in-file": "^6.3.2",
+    "semver": "^7.3.8",
     "sine-waves": "^0.3.0",
     "url-loader": "^4.1.1"
   },
@@ -69,6 +71,7 @@
     "@docusaurus/types": "2.2.0",
     "@tsconfig/docusaurus": "^1.0.6",
     "@types/lodash": "^4.14.188",
+    "@types/semver": "^7.3.13",
     "autoprefixer": "^10.4.0",
     "highlight.js": "^9.7.0",
     "marked": "^0.3.6",

release-notes/pulsar.mdx

@@ -10,6 +10,8 @@ import pulsar from "../data/release-pulsar"
 
 ## Release notes
 
+Read more about Pulsar's [release policy](pathname:///contribute/release-policy).
+
 <PulsarReleaseTable data={pulsar} />
 
 ## Previous versions

sidebarsDevelopment.js

@@ -48,6 +48,7 @@ const sidebars = {
             type: "category",
             label: "Releases",
             items: [
+                'release-policy',
                 {
                     type: "category",
                     label: 'Release process',
@@ -58,7 +59,6 @@ const sidebars = {
                     ]
                 },
                 'validate-release-candidate',
-                'version-policy',
             ]
         },
         {