You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by mm...@apache.org on 2023/02/28 16:43:33 UTC
[pulsar-site] branch main updated: [improve][doc] Release policy and matrix (#433)
This is an automated email from the ASF dual-hosted git repository.
mmerli pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 2cb5139b355 [improve][doc] Release policy and matrix (#433)
2cb5139b355 is described below
commit 2cb5139b3556bcf04d9fdabba7caa65c9b6a2c4d
Author: tison <wa...@gmail.com>
AuthorDate: Wed Mar 1 00:43:26 2023 +0800
[improve][doc] Release policy and matrix (#433)
* reorder sidebars
Signed-off-by: tison <wa...@gmail.com>
* version-policy -> release-policy
Signed-off-by: tison <wa...@gmail.com>
* Merge PIP-175 release policy
Signed-off-by: tison <wa...@gmail.com>
* Add 2.11
Signed-off-by: tison <wa...@gmail.com>
* fix whitespace
Signed-off-by: tison <wa...@gmail.com>
* data-driven SupportedVersionsTable
Signed-off-by: tison <wa...@gmail.com>
* add render
Signed-off-by: tison <wa...@gmail.com>
* better datetime render
Signed-off-by: tison <wa...@gmail.com>
* colored support
Signed-off-by: tison <wa...@gmail.com>
* drop manual table
Signed-off-by: tison <wa...@gmail.com>
* light color
Signed-off-by: tison <wa...@gmail.com>
* background to dot and color
Signed-off-by: tison <wa...@gmail.com>
* bold
Signed-off-by: tison <wa...@gmail.com>
* write release cycle in steps
Signed-off-by: tison <wa...@gmail.com>
* support version table is now data-driven
Signed-off-by: tison <wa...@gmail.com>
* Addres comments
Signed-off-by: tison <wa...@gmail.com>
* Update contribute/release-policy.md
Co-authored-by: Jun Ma <60...@users.noreply.github.com>
* Update contribute/release-policy.md
---------
Signed-off-by: tison <wa...@gmail.com>
Co-authored-by: Jun Ma <60...@users.noreply.github.com>
---
contribute/release-policy.md | 89 +++++++++++++++
contribute/release-process.md | 30 +++--
contribute/version-policy.md | 46 --------
package.json | 3 +
release-notes/pulsar.mdx | 2 +
sidebarsDevelopment.js | 2 +-
src/components/SupportedVersionsTable.tsx | 178 ++++++++++++++++++++++++++++++
static/.htaccess | 3 +-
8 files changed, 289 insertions(+), 64 deletions(-)
diff --git a/contribute/release-policy.md b/contribute/release-policy.md
new file mode 100644
index 00000000000..f33d2aa146c
--- /dev/null
+++ b/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)
diff --git a/contribute/release-process.md b/contribute/release-process.md
index be1635add9b..7b576e64362 100644
--- a/contribute/release-process.md
+++ b/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.
:::
diff --git a/contribute/version-policy.md b/contribute/version-policy.md
deleted file mode 100644
index 945ed500d8a..00000000000
--- a/contribute/version-policy.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-id: version-policy
-title: Version policy
----
-
-The Pulsar project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). Existing releases can expect
-patches for bugs and security vulnerabilities. New features will target minor releases.
-
-When upgrading an existing cluster, it is important to upgrade components linearly through each minor version. For
-example, when upgrading from 2.8.x to 2.10.x, it is important to upgrade to 2.9.x before going to 2.10.x.
-
-## Supported Versions
-
-Feature release branches will be maintained with security-fix and bug-fix releases for at least 12 months after the
-initial release. For example, branch 2.5.x is no longer considered maintained as of January 2021, 12 months after
-the release of 2.5.0 in January 2020. No more 2.5.x releases should be expected at this point, even to fix security
-vulnerabilities.
-
-Note that a minor version can be maintained past its 12-month initial support period. For example, version 2.7 is still
-actively maintained.
-
-Security fixes will be given priority when it comes to back porting fixes to older versions that are within the
-supported time window. It is challenging to decide which bug fixes to back port to old versions. As such, the latest
-versions will have the most bug fixes.
-
-When 3.0.0 is released, the community will decide how to continue supporting 2.x. The last minor release within 2.x may
-be maintained for longer as an "LTS" release, but it has not been officially decided.
-
-The following table shows version support timelines and will be updated with each release.
-
-| Version | Supported | Initial Release | At Least Until |
-|:-------:|:------------------:|:---------------:|:--------------:|
-| 2.10.x | :white_check_mark: | April 2022 | April 2023 |
-| 2.9.x | :white_check_mark: | November 2021 | November 2022 |
-| 2.8.x | :white_check_mark: | June 2021 | June 2022 |
-| 2.7.x | :white_check_mark: | November 2020 | November 2021 |
-| 2.6.x | :x: | June 2020 | June 2021 |
-| 2.5.x | :x: | January 2020 | January 2021 |
-| 2.4.x | :x: | July 2019 | July 2020 |
-| < 2.3.x | :x: | - | - |
-
-If there is ambiguity about which versions of Pulsar are actively supported, please ask on the [users@pulsar.apache.org](mailto:users@pulsar.apache.org) mailing list.
-
-## Release Frequency
-
-With the acceptance of [PIP-47 - A Time-Based Release Plan](https://github.com/apache/pulsar/wiki/PIP-47%3A-Time-Based-Release-Plan), the Pulsar community aims to complete 4 minor releases each year. Patch releases are completed based on demand as well as need, in the event of security fixes.
diff --git a/package.json b/package.json
index b99f3ff956f..e8e94cb85cb 100644
--- a/package.json
+++ b/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",
diff --git a/release-notes/pulsar.mdx b/release-notes/pulsar.mdx
index 97c39e997b6..b75ccb26f94 100644
--- a/release-notes/pulsar.mdx
+++ b/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
diff --git a/sidebarsDevelopment.js b/sidebarsDevelopment.js
index 99fb7f3d93f..2deef63ac30 100644
--- a/sidebarsDevelopment.js
+++ b/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',
]
},
{
diff --git a/src/components/SupportedVersionsTable.tsx b/src/components/SupportedVersionsTable.tsx
new file mode 100644
index 00000000000..8de09d136b0
--- /dev/null
+++ b/src/components/SupportedVersionsTable.tsx
@@ -0,0 +1,178 @@
+import lodash from 'lodash'
+import React from 'react'
+import semver from "semver/preload"
+import {Stack, Table, TableBody, TableCell, TableHead, TableRow} from "@mui/material"
+
+import releases from '@site/data/release-pulsar'
+import Link from "@docusaurus/Link";
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import moment from "moment";
+import {styled} from "@mui/system";
+
+type SimpleReleaseData = {
+ version: semver.SemVer,
+ released: moment.Moment,
+ releaseNoteLink: string,
+};
+
+type SupportedVersionData = {
+ version: semver.SemVer,
+ released: moment.Moment,
+ activeSupport: moment.Moment,
+ securitySupport: moment.Moment,
+ latest: semver.SemVer,
+ latestReleased: moment.Moment,
+ latestReleaseNoteLink: string,
+};
+
+function resolveActiveSupport(version: semver.SemVer, released: moment.Moment): moment.Moment {
+ const support = moment(released)
+ if (version.compareMain('3.0.0') < 0) {
+ // before 3.0 - active support for 12 months
+ return support.add(12, 'months')
+ } else if (version.minor > 0) {
+ // regular release - active support for 6 months
+ return support.add(6, 'months')
+ } else {
+ // LTS release - active support for 24 months
+ return support.add(24, 'months')
+ }
+}
+
+function resolveSecuritySupport(version: semver.SemVer, released: moment.Moment): moment.Moment {
+ const support = moment(released)
+ if (version.compareMain('3.0.0') < 0) {
+ // before 3.0 - security support for 12 months
+ return support.add(12, 'months')
+ } else if (version.minor > 0) {
+ // regular release - security support for 6 months
+ return support.add(6, 'months')
+ } else {
+ // LTS release - security support for 36 months
+ return support.add(36, 'months')
+ }
+}
+
+function isSameFeatureRelease(v1: semver.SemVer, v2: semver.SemVer): boolean {
+ return v1.major == v2.major && v1.minor == v2.minor
+}
+
+function renderVersionCell(version: semver.SemVer): JSX.Element {
+ if (version.compareMain('3.0.0') < 0) {
+ return <TableCell>{version.major}.{version.minor}</TableCell>
+ } else if (version.minor != 0) {
+ return <TableCell>{version.major}.{version.minor}</TableCell>
+ } else {
+ return <TableCell>{version.major}.{version.minor} (LTS)</TableCell>
+ }
+}
+
+function renderReleasedCell(released: moment.Moment): JSX.Element {
+ return <TableCell><>
+ {released.fromNow()}
+ <br/>
+ ({released.format('DD MMM YYYY')})
+ </>
+ </TableCell>
+}
+
+const Dot = styled('div')({
+ width: 15,
+ height: 15,
+ borderRadius: '50%',
+});
+
+function renderSupportCell(support: moment.Moment): JSX.Element {
+ const now = moment()
+ return <TableCell><>
+ <Stack direction="row" spacing={2}>
+ <div style={{marginTop: 10}}>
+ <Dot style={{background: support.isBefore(now) ? 'crimson' : 'mediumaquamarine'}}/>
+ </div>
+ <div style={{color: support.isBefore(now) ? 'crimson' : 'inherit'}}>
+ {support.isBefore(now) ? "Ended" : "End"} {support.fromNow()}
+ <br/>
+ ({support.format('DD MMM YYYY')})
+ </div>
+ </Stack>
+ </>
+ </TableCell>
+}
+
+function renderLatestVersionCell(d: SupportedVersionData): JSX.Element {
+ const now = moment()
+ if (d.activeSupport.isBefore(now) && d.securitySupport.isBefore(now)) {
+ // no longer supported
+ return <TableCell>
+ <del>{d.latest.version}</del>
+ </TableCell>
+ }
+
+ return <TableCell><>
+ <Link href={useBaseUrl(d.latestReleaseNoteLink)}>{d.latest.version}</Link>
+ <br/>
+ ({d.latestReleased.format('DD MMM YYYY')})
+ </>
+ </TableCell>
+}
+
+export default function SupportedVersionsTable(): JSX.Element {
+ let releaseList: SimpleReleaseData[] = releases.map(r => ({
+ version: semver.coerce(r.tagName),
+ released: moment(r.publishedAt),
+ releaseNoteLink: r.releaseNotes,
+ }))
+ releaseList.sort((o1, o2) => semver.rcompare(o1.version, o2.version))
+
+ let supportedVersionList: SupportedVersionData[] = []
+ for (const release of releaseList) {
+ const version = release.version
+ const released = release.released
+ const last = lodash.last(supportedVersionList)
+ if (last && isSameFeatureRelease(last.version, release.version)) {
+ // early patch release - the support period is counted from the first patch release
+ last.released = release.released
+ last.activeSupport = resolveActiveSupport(last.version, last.released)
+ last.securitySupport = resolveSecuritySupport(last.version, last.released)
+ continue
+ }
+ supportedVersionList.push({
+ version: version,
+ released: released,
+ activeSupport: resolveActiveSupport(version, released),
+ securitySupport: resolveSecuritySupport(version, released),
+ latest: version,
+ latestReleased: released,
+ latestReleaseNoteLink: release.releaseNoteLink,
+ })
+ }
+
+ const TableHeaderCell = styled(TableCell)({fontWeight: "bold"})
+
+ return <>
+ <Table>
+ <TableHead>
+ <TableRow>
+ <TableHeaderCell>Version</TableHeaderCell>
+ <TableHeaderCell>Released</TableHeaderCell>
+ <TableHeaderCell>Active Support</TableHeaderCell>
+ <TableHeaderCell>Security Support</TableHeaderCell>
+ <TableHeaderCell>Latest</TableHeaderCell>
+ </TableRow>
+ </TableHead>
+ <TableBody>
+ {
+ supportedVersionList.map(r => <>
+ <TableRow>
+ {renderVersionCell(r.version)}
+ {renderReleasedCell(r.released)}
+ {renderSupportCell(r.activeSupport)}
+ {renderSupportCell(r.securitySupport)}
+ {renderLatestVersionCell(r)}
+ </TableRow>
+ </>)
+ }
+ </TableBody>
+ </Table>
+ </>
+}
diff --git a/static/.htaccess b/static/.htaccess
index 065dce262fa..272ee541085 100755
--- a/static/.htaccess
+++ b/static/.htaccess
@@ -21,7 +21,8 @@ RewriteRule "^docs/(.*)$" "/docs/2.11.x/$1" [R=301,DPI,L]
RewriteRule "^docs/(.+/)?develop-binary-protocol/?$" "/docs/$1developing-binary-protocol" [R=301,DPI,L]
RewriteRule "^docs/(.+/)?administration-dashboard/?$" "/docs/$1administration-pulsar-manager" [R=301,DPI,L]
RewriteRule "^docs/(.+/)?security-tls-keystore/?$" "/docs/$1security-tls-authentication" [R=301,DPI,L]
-RewriteRule "^docs/(.+/)?security-policy-and-supported-versions/?$" "/contribute/version-policy" [R=301,DPI,L]
+RewriteRule "^docs/(.+/)?security-policy-and-supported-versions/?$" "/contribute/release-policy" [R=301,DPI,L]
+RewriteRule "^contribute/version-policy/?$" "/contribute/release-policy" [R=301,DPI,L]
RewriteRule "^coding-guide/?$" "/contribute/develop-coding-conventions" [R=301,DPI,L]
RewriteRule "^contributing/?$" "/contribute" [R=301,DPI,L]