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 <[email protected]>
AuthorDate: Wed Mar 1 00:43:26 2023 +0800
[improve][doc] Release policy and matrix (#433)
* reorder sidebars
Signed-off-by: tison <[email protected]>
* version-policy -> release-policy
Signed-off-by: tison <[email protected]>
* Merge PIP-175 release policy
Signed-off-by: tison <[email protected]>
* Add 2.11
Signed-off-by: tison <[email protected]>
* fix whitespace
Signed-off-by: tison <[email protected]>
* data-driven SupportedVersionsTable
Signed-off-by: tison <[email protected]>
* add render
Signed-off-by: tison <[email protected]>
* better datetime render
Signed-off-by: tison <[email protected]>
* colored support
Signed-off-by: tison <[email protected]>
* drop manual table
Signed-off-by: tison <[email protected]>
* light color
Signed-off-by: tison <[email protected]>
* background to dot and color
Signed-off-by: tison <[email protected]>
* bold
Signed-off-by: tison <[email protected]>
* write release cycle in steps
Signed-off-by: tison <[email protected]>
* support version table is now data-driven
Signed-off-by: tison <[email protected]>
* Addres comments
Signed-off-by: tison <[email protected]>
* Update contribute/release-policy.md
Co-authored-by: Jun Ma <[email protected]>
* Update contribute/release-policy.md
---------
Signed-off-by: tison <[email protected]>
Co-authored-by: Jun Ma <[email protected]>
---
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 [email protected] 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 [[email protected]](mailto:[email protected])
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]
