This is an automated email from the ASF dual-hosted git repository.
tison 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 0b70be67bbb [fix][doc] Update contribution guide according to recent
changes (#351)
0b70be67bbb is described below
commit 0b70be67bbb09ee62e78e974313ff5dbb2976d64
Author: tison <[email protected]>
AuthorDate: Sat Dec 31 00:10:36 2022 +0800
[fix][doc] Update contribution guide according to recent changes (#351)
Signed-off-by: tison <[email protected]>
---
contribute/assets/release-note-guide-example.png | Bin 273286 -> 0 bytes
contribute/become-core-developer.md | 2 +-
contribute/create-gpg-keys.md | 2 +-
contribute/develop-semantic-title.md | 4 +-
contribute/document-contribution.md | 54 +--
contribute/document-intro.md | 23 +-
contribute/document-preview.md | 94 +----
contribute/document-syntax.md | 4 +-
.../{assets => media}/client-matrix-workflow.png | Bin
.../{assets => media}/obtain-github-permalink.png | Bin
.../semantic-pull-request-title.png | Bin
contribute/{assets => media}/website-preview.png | Bin
contribute/release-note-guide.md | 71 ++--
contribute/release-process.md | 453 +++++++++++----------
contribute/setup-building.md | 2 +-
contribute/testing-licenses.md | 2 +-
contribute/validate-release-candidate.md | 2 +-
contribute/version-policy.md | 2 +-
docs/about.md | 2 +-
docs/client-libraries.md | 6 +-
sidebarsDevelopment.js | 4 +-
src/pages/contributing.md | 7 +-
tools/pytools/bin/reference-doc-generator.py | 23 +-
.../version-2.10.x/security-tls-transport.md | 2 +-
.../version-2.2.0/security-tls-transport.md | 2 +-
.../version-2.2.1/security-tls-transport.md | 2 +-
.../version-2.3.0/security-tls-transport.md | 2 +-
.../version-2.3.1/security-tls-transport.md | 2 +-
.../version-2.3.2/security-tls-transport.md | 2 +-
.../version-2.4.0/security-tls-transport.md | 2 +-
.../version-2.4.1/security-tls-transport.md | 2 +-
.../version-2.4.2/security-tls-transport.md | 2 +-
.../version-2.5.0/security-tls-transport.md | 2 +-
.../version-2.5.1/security-tls-transport.md | 2 +-
.../version-2.5.2/security-tls-transport.md | 2 +-
.../version-2.6.0/security-tls-transport.md | 2 +-
.../version-2.6.1/security-tls-transport.md | 2 +-
.../version-2.6.2/security-tls-transport.md | 2 +-
.../version-2.6.3/security-tls-transport.md | 2 +-
.../version-2.6.4/security-tls-transport.md | 2 +-
.../version-2.7.0/security-tls-transport.md | 2 +-
.../version-2.7.1/security-tls-transport.md | 2 +-
.../version-2.7.2/security-tls-transport.md | 2 +-
.../version-2.7.3/security-tls-transport.md | 2 +-
.../version-2.7.4/security-tls-transport.md | 2 +-
.../version-2.7.5/security-tls-transport.md | 2 +-
.../version-2.8.x/security-tls-transport.md | 2 +-
.../version-2.9.x/security-tls-transport.md | 2 +-
48 files changed, 366 insertions(+), 441 deletions(-)
diff --git a/contribute/assets/release-note-guide-example.png
b/contribute/assets/release-note-guide-example.png
deleted file mode 100644
index 25120c886e6..00000000000
Binary files a/contribute/assets/release-note-guide-example.png and /dev/null
differ
diff --git a/contribute/become-core-developer.md
b/contribute/become-core-developer.md
index 512cdea18eb..9aa0e54ba5f 100644
--- a/contribute/become-core-developer.md
+++ b/contribute/become-core-developer.md
@@ -1,6 +1,6 @@
---
id: become-core-developer
-title: How to Become a Core Developer
+title: How to become a core developer
---
The Pulsar community follows [the Apache governance
model](https://www.apache.org/foundation/how-it-works.html#roles).
diff --git a/contribute/create-gpg-keys.md b/contribute/create-gpg-keys.md
index a5fdc8cd12a..51b72582adb 100644
--- a/contribute/create-gpg-keys.md
+++ b/contribute/create-gpg-keys.md
@@ -1,6 +1,6 @@
---
id: create-gpg-keys
-title: Create GPG keys
+title: Creating GPG keys
---
This page provides instructions for Pulsar committers on how to do the initial
GPG setup.
diff --git a/contribute/develop-semantic-title.md
b/contribute/develop-semantic-title.md
index a474b1bc3da..d28e751ee76 100644
--- a/contribute/develop-semantic-title.md
+++ b/contribute/develop-semantic-title.md
@@ -1,6 +1,6 @@
---
id: develop-semantic-title
-title: Conventional Commits
+title: Conventional commits
---
This guide explains why you need good PR titles and how you do write PR titles
in Conventional Commits spec.
@@ -32,7 +32,7 @@ Good titles often bring many benefits, including but not
limited to the followin
A PR title should be structured as follows:
-
+
The rule can be interpreted as: A good title = clear format ([type](#type) and
[scope](#scope)) + self-explanatory [summary](#summary).
diff --git a/contribute/document-contribution.md
b/contribute/document-contribution.md
index 0d91ee8145e..f99d410b0f0 100644
--- a/contribute/document-contribution.md
+++ b/contribute/document-contribution.md
@@ -1,29 +1,17 @@
---
id: document-contribution
-title: Contribution
+title: Updating document
---
This guide explains the organization of Pulsar documentation and website repos
and the workflow of updating various Pulsar documents.
## Source repositories
-Currently, the source of documents and website (where the docs are finally
published) are located in two repositories:
-
-| Type | Location
| Description
|
-|---------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Documentation | [pulsar](https://github.com/apache/pulsar/tree/master/site2)
| All files related to Pulsar documentation are stored in this repo.
|
-| Website | [pulsar-site](https://github.com/apache/pulsar-site)
| 1. All files related to the Pulsar website are stored in the **main** branch
in this repo. <br/> 2. The website is built and put in in the **asf-site-next**
branch in this repo. |
-
-Documents in the `pulsar` repo are synced to the `pulsar-site` repo every 6
hours, following the rules:
-
-| Source (pulsar) | Destination (pulsar-site) |
-|--------------------|---------------------------|
-| site2/website | site2/website-next |
-| site2/docs | site2/website-next/docs |
+Currently, the source of documents and website (where the docs are finally
published) are located at the
[apache/pulsar-site](https://github.com/apache/pulsar-site) repo.
## Update versioned docs
-If you want to update versioned docs, go to [site2/website/versioned_docs/
folder under the main
repo](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs)
to find your desired one.
+If you want to update versioned docs, go to [versioned_docs
folder](https://github.com/apache/pulsar-site/tree/main/versioned_docs) to find
your desired one.
For versions prior to 2.8, Pulsar releases versioned docs for each patch
release. You can update the exact versioned doc.
@@ -39,18 +27,12 @@ This <fix / improvment> is available for 2.8.2 and later
versions.
:::
```
-:::note
-
-Read [PIP-190: Simplify documentation release and maintenance
strategy](https://github.com/apache/pulsar/issues/16637) for more information.
-
-:::
-
## Update reference docs
-If you want to update [Pulsar configuration
docs](https://pulsar.apache.org/reference/#/latest/), pay attention to the doc
source files.
+If you want to update [Pulsar reference docs](pathname:///reference/), you
should update the corresponding source files.
-- Some docs are generated from code **automatically**. If you want to update
the docs, you need to update the source code files.
-- Some configuration docs are updated **manually** using markdown files.
+* Some reference docs are generated from code **automatically**. If you want
to update the docs, you need to update the source code files.
+* Some configuration docs are updated **manually** using markdown files.
### Update configuration docs
@@ -69,12 +51,12 @@ Docs for configs of bundled components are generated from
command-line tools **a
Docs for configs of external components (whose source code is hosted outside
the Pulsar repositories) are updated **manually**:
-| Components | Update where ...
|
-|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| BookKeeper |
[reference-configuration-bookkeeper.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/config/reference-configuration-bookkeeper.md)
|
-| Log4j |
[reference-configuration-log4j.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/config/reference-configuration-log4j.md)
|
-| Log4j shell |
[reference-configuration-log4j-shell.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/config/reference-configuration-log4j-shell.md)
|
-| ZooKeeper |
[reference-configuration-zookeeper.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/config/reference-configuration-zookeeper.md)
|
+| Components | Update where ...
|
+|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| BookKeeper |
[reference-configuration-bookkeeper.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/config/reference-configuration-bookkeeper.md)
|
+| Log4j |
[reference-configuration-log4j.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/config/reference-configuration-log4j.md)
|
+| Log4j shell |
[reference-configuration-log4j-shell.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/config/reference-configuration-log4j-shell.md)
|
+| ZooKeeper |
[reference-configuration-zookeeper.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/config/reference-configuration-zookeeper.md)
|
### Update command-line tool docs
@@ -89,11 +71,11 @@ Docs for bundled Java-based command-line tools are
generated **automatically**:
Docs for external command-line tools or bare scripts are updated **manually**:
-| Components | Update where…
|
-|---------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| pulsar-shell |
[pulsar-shell.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/pulsar-shell/pulsar-shell.md)
|
-| pulsar-daemon |
[pulsar-daemon.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/pulsar-daemon/pulsar-daemon.md)
|
-| bookkeeper |
[bookkeeper.md](https://github.com/apache/pulsar-site/blob/main/site2/website-next/static/reference/next/bookkeeper/bookkeeper.md)
|
+| Components | Update where…
|
+|---------------|--------------------------------------------------------------------------------------------------------------------------|
+| pulsar-shell |
[pulsar-shell.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/pulsar-shell/pulsar-shell.md)
|
+| pulsar-daemon |
[pulsar-daemon.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/pulsar-daemon/pulsar-daemon.md)
|
+| bookkeeper |
[bookkeeper.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/bookkeeper/bookkeeper.md)
|
## Update client/function matrix
@@ -112,4 +94,4 @@ If you want to update the Pulsar Feature Matrix, follow the
steps below.
2. Get your PR reviewed and merged.
3. In the [Pulsar Feature
Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914),
check the box in the corresponding cell with the links of PRs and doc site.
-
+
diff --git a/contribute/document-intro.md b/contribute/document-intro.md
index 974d54984bd..878388804ff 100644
--- a/contribute/document-intro.md
+++ b/contribute/document-intro.md
@@ -8,29 +8,30 @@ Good documentation is crucial for any kind of software. This
is especially true
This introduction provides a set of guides offering best-practice suggestions
for contributing documentation to Pulsar. It provides detailed instructions on
the contribution workflow and conventions. Please follow these guidelines to
keep the documentation structure, style, and syntax consistent.
-## Before writing documents
-
-* [Contribution Guide](document-contribution.md)
- * Documentation structure and organization
- * Workflow of submitting various docs
-
## Writing documents
+* [How to update document](document-contribution.md)
* [Writing Syntax Guide](document-syntax.md)
* [Writing Style
Guide](https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#)
* [Design Style
Guide](https://docs.google.com/document/d/16Hp7Sc86MQtL0m8fc2w_TrcKXAuglwRwHmdmwfk00mI/edit#heading=h.b8ogodj5sj0)
* [API Documentation
Guide](https://docs.google.com/document/d/1-I1oQp1_HUaQopqilU-JdC-ksrLAgYNi93FZVnECwV8/edit#heading=h.wu6ygjne8e35)
-## Testing documents
+## Testing changes
+
+* [How to preview changes](document-preview.md)
-* [Content Preview Guide](document-preview.md)
+## Submitting changes
-## Preparing to submit doc PRs
+### Convention
* [Labels](develop-labels.md)
-* [Conventional Commits](develop-semantic-title.md)
+* [Conventional commits](develop-semantic-title.md)
+
+### Pull request process
+
+* [Creating a pull request from a
fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
-## References
+## Reference
In addition, the following resources can help you craft and contribute to docs:
diff --git a/contribute/document-preview.md b/contribute/document-preview.md
index 7891fd72139..c935883fe53 100644
--- a/contribute/document-preview.md
+++ b/contribute/document-preview.md
@@ -1,6 +1,6 @@
---
id: document-preview
-title: Content Preview
+title: Previewing content
---
This guide explains why and how to preview Pulsar content locally with
detailed steps and various examples.
@@ -9,12 +9,12 @@ This guide explains why and how to preview Pulsar content
locally with detailed
It is **required** to preview your changes locally and attach the preview
screenshots in your PR description. It brings many benefits, including but not
limited to:
-* You can test your writings. It's a way to check whether you use the correct
[syntax](document-syntax.md) and debug issues. You **must ensure** docs can be
compiled and published correctly.
+* You can test your writings. It's a way to check whether you use the correct
[syntax](document-syntax.md). You **must ensure** docs can be compiled and
published correctly.
* You can get your PR merged more quickly. Reviewers know your changes clearly
and can speed up the review process.
## How to preview changes locally?
-Pulsar documentation is built using Docusaurus. To preview your changes as you
edit the files, you can run a local development server that serves your website
and reflect the latest changes.
+Pulsar documentation is built using [Docusaurus](https://docusaurus.io/). To
preview your changes as you edit the files, you can run a local development
server that serves your website and reflect the latest changes.
### Prerequisites
@@ -24,71 +24,15 @@ To verify docs are built correctly before submitting a
contribution, you should
* Yarn >= 1.5
* Although you can use Linux, macOS, or Windows to build locally the Pulsar
documentation, macOS is the preferred build environment as it offers the most
complete support for documentation building.
-### Preview documentation changes
-
-Follow these steps to preview documentation changes on the **master** branch.
-
-1. Change to the working directory:
-
- ```bash
- cd pulsar/site2/website
- ```
-
-2. Run the following command to preview changes:
-
- ```bash
- # Preview changes on latest stable version
- sh start.sh
-
- # Preview changes on a specific version version
- sh start.sh 2.10.x
-
- # Preview changes on multiple versions
- sh start.sh 2.10.x 2.9.x ...
- ```
-
- By default, a browser window will open at http://localhost:3000 to show the
changes.
-
- :::tip
-
- If you want to preview changes on `master`, change the URL to
`http://localhost:3000/docs/next`.
-
- :::
-
- 
-
-### Preview Java API document changes
-
-Follow these steps to preview Java API document changes on the **master**
branch.
-
-1. Change to the working directory:
-
- ```bash
- cd pulsar/site2/tools
- ```
-
-2. Run the following command to generate the `.html` files:
-
- ```bash
- sh javadoc-gen.sh
- ```
-
-3. Open the target `.html` file to preview the updates.
-
- Supposed you change JavaDoc for `ConsumerBuilder.java`:
-
- ```bash
- cd generated-site/api/client/{version}/org/apache/pulsar/client/api/
- open ConsumerBuilder.html
- ```
-
-### Preview website changes
+### Preview changes
Pulsar website changes refer to all the changes made to the Pulsar website,
including but not limited to the following pages:
-* [Release Notes page](pathname:///release-notes/)
+* [User documents](pathname:///docs)
+* [Contribution guide](about.md)
+* [Release notes](pathname:///release-notes/)
* [Ecosystem page](pathname:///ecosystem)
-* [Case studies page](pathname:///case-studies)
+* [Case studies](pathname:///case-studies)
* ...
Follow these steps to preview the website changes.
@@ -96,21 +40,25 @@ Follow these steps to preview the website changes.
1. Change to the working directory:
```bash
- cd pulsar-site/site2/website-next
+ cd pulsar-site/
```
2. Run the following command to preview changes:
-
+
```bash
- # Preview changes on master
- ./preview.sh current
+ # Preview changes on master
+ ./preview.sh current
- # preview changes on a specific version
- ./preview.sh 2.10.x
+ # preview changes on a specific version
+ ./preview.sh 2.10.x
- # preview changes on multiple versions
- ./preview.sh 2.10.x 2.9.x ...
- ```
+ # preview changes on multiple versions
+ ./preview.sh 2.10.x 2.9.x ...
+ ```
+
+By default, a browser window will open at
[http://localhost:3000](http://localhost:3000) to show the changes:
+
+
### Stop preview
diff --git a/contribute/document-syntax.md b/contribute/document-syntax.md
index 9ecf73cbc8c..f31f01e2327 100644
--- a/contribute/document-syntax.md
+++ b/contribute/document-syntax.md
@@ -1,6 +1,6 @@
---
id: document-syntax
-title: Writing Syntax
+title: Writing syntax guide
---
````mdx-code-block
@@ -268,7 +268,7 @@ For example, if you're describing a feature in Microsoft's
Active Directory, inc
Use a **permalink** when linking to a specific line in a file to ensure users
land on the line you're referring to though lines of code change over time.
-
+
### Authoritative sources
diff --git a/contribute/assets/client-matrix-workflow.png
b/contribute/media/client-matrix-workflow.png
similarity index 100%
rename from contribute/assets/client-matrix-workflow.png
rename to contribute/media/client-matrix-workflow.png
diff --git a/contribute/assets/obtain-github-permalink.png
b/contribute/media/obtain-github-permalink.png
similarity index 100%
rename from contribute/assets/obtain-github-permalink.png
rename to contribute/media/obtain-github-permalink.png
diff --git a/contribute/assets/semantic-pull-request-title.png
b/contribute/media/semantic-pull-request-title.png
similarity index 100%
rename from contribute/assets/semantic-pull-request-title.png
rename to contribute/media/semantic-pull-request-title.png
diff --git a/contribute/assets/website-preview.png
b/contribute/media/website-preview.png
similarity index 100%
rename from contribute/assets/website-preview.png
rename to contribute/media/website-preview.png
diff --git a/contribute/release-note-guide.md b/contribute/release-note-guide.md
index 27575d450e9..0802e7fcacd 100644
--- a/contribute/release-note-guide.md
+++ b/contribute/release-note-guide.md
@@ -1,71 +1,58 @@
---
id: release-note-guide
-title: Release Note Guide
+title: Writing release notes
---
-This guide explains everything about Pulsar release notes.
+Pulsar release notes consist of the following parts:
-## Intro to release notes
+* [Core](pathname:///release-notes/)
+* [Java client](pathname:///release-notes/client-java)
+* [WebSocket client](pathname:///release-notes/client-ws)
+* [C++ client](pathname:///release-notes/client-cpp)
+* [Python client](pathname:///release-notes/client-python)
+* [Go client](pathname:///release-notes/client-go)
+* [Node.js client](pathname:///release-notes/client-node)
+* [C# client](pathname:///release-notes/client-cs)
-This chapter gives an overview of Pulsar release notes.
+## Prerequisite
-### Basic info
+To generate release notes, you are suggested to install the [GitHub
CLI](https://cli.github.com/) and authenticate first:
-[Pulsar release notes](/release-notes/) consist of the following parts.
-
-| Release note | Component
|
-|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------|
-| [Pulsar Core](/release-notes/#pulsar-release-notes) | Pulsar
|
-| [Pulsar Clients](/docs/client-libraries.md) |
<ul><li>Java</li><li>WebSocket</li><li>C++</li><li>Python</li><li>Go</li><li>NodeJs</li><li>C#</li></ul>
|
-
-### Maintenance info
-
-To generate release note page, you're suggested to install the [GitHub
CLI](https://cli.github.com/) and authenticate first.
+```shell
+brew install gh
+gh auth login
+```
-1. Fetch the release metadata:
+## Fetch the release metadata
```bash
# Replace v2.10.2 with the target version tag
+# Replace apache/pulsar with the component repo
gh release view "v2.10.2" -R apache/pulsar --json author,tagName,publishedAt
```
-2. Fetch the release notes:
+## Fetch the release note
```bash
# Replace v2.10.2 with the target version tag
+# Replace apache/pulsar with the component repo
gh release view "v2.10.2" -R apache/pulsar --json body --jq .body
```
-3. Select the related release notes entries and add a [versioned release
note](https://github.com/apache/pulsar-site/tree/main/site2/website-next/release-notes/versioned).
-4. Update the metadata file
[site2/website-next/data/release-*.js](https://github.com/apache/pulsar-site/tree/main/site2/website-next/data).
+## Update the release note page
-The process is similar to update standalone client releases.
+1. Copy the related release notes entries and add a [versioned release note
file](https://github.com/apache/pulsar-site/tree/main/release-notes/versioned).
+2. Update the [version metadata
files](https://github.com/apache/pulsar-site/tree/main/data) (`release-*.js`).
To preview the result, follow the instructions documented at the [Content
Preview Guide](document-preview.md#preview-website-changes).
-## Submit release notes
-
-Follow the steps below to submit release notes for Pulsar and clients (**Java
and WebSocket**).
-
-:::note
-
-For C++, Python, Go, Node.js, and C# clients, you do not need to take care of
them since their release notes are synced from their repos to the [Pulsar
Release Note page](/release-notes/).
-
-:::
+## Submit the release note
-1. Submit a PR to add separate release notes for Pulsar and clients (Java and
WebSocket) to [versioned release-notes
folder](https://github.com/apache/pulsar-site/tree/main/site2/website-next/release-notes/versioned).
-2. Get this PR reviewed and merged.
-3. Copy the release note to the [Pulsar Releases Page on
GitHub](https://github.com/apache/pulsar/releases).
+Submit a PR against [the site repo](https://github.com/apache/pulsar-site)
with the added version release note file and updated version metadata files.
- | Component | Step
|
-
|---------------------------------------|----------------------------------------------------------------------------|
- | Pulsar Core | Copy the release note content.
|
- | Pulsar Clients (Java, WebSocket, ...) | Create independent sections for
each client and copy release note content. |
-
- Examples for Java clent's release note:
-
- 
+Here are some examples:
- After the new release is published, all the information about the release
is automatically added to the [Pulsar Release Note page](/release-notes/).
+* [Add the release note for C++ client
3.1.0](https://github.com/apache/pulsar-site/pull/326)
+* [Add the release note for Python client
3.0.0](https://github.com/apache/pulsar-site/pull/343)
-4. Check whether the release information is shown on the [Pulsar Release Note
page](/release-notes/) after the website is updated and built successfully.
+Check whether the release information is shown on the [Pulsar Release Note
page](pathname:///release-notes/) after the website is updated and built
successfully.
diff --git a/contribute/release-process.md b/contribute/release-process.md
index 57c513a23d6..7551d623e98 100644
--- a/contribute/release-process.md
+++ b/contribute/release-process.md
@@ -1,58 +1,57 @@
---
id: release-process
-title: Release Process
+title: Release process
---
This page contains instructions for Pulsar committers on how to perform a
release.
-:::note
-
-The term `major/minor releases` used throughout this document is defined as
follows:
+The term major/minor 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.
-:::
-
## Preparation
-Open a discussion in [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.
+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-2.X.0` once
all PRs with the 2.X.0 milestone are merged. If some PRs with the 2.X.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 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 minor releases, if there are no disagreements, you should cherry-pick all
merged PRs with the `release/X.Y.Z` labels into `branch-X.Y`. After these PRs
are cherry-picked, you should add the `cherry-picked/branch-X.Y` labels.
+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.
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.
For PRs that are still open, you can choose to delay them to the next release
or ping others to review so that they can be merged.
-To verify the release branch is not broken, you can synchronize the branch in
your private repo and open a PR to trigger the CI. Example:
https://github.com/BewareMyPower/pulsar/pull/3
+To verify the release branch is not broken, you can synchronize the branch in
your personal repo and open a PR to trigger the CI.
+
+You can use the following command to catch basic compilation, checkstyle or
spotbugs errors in your local env before cherry-picking.
+
+```bash
+mvn clean install -DskipTests
+```
-> You can use the following command to catch basic compilation or checkstyle
errors in your local env before cherry-picking.
->
-> ```bash
-> mvn -Pcore-modules,-main -T 1C clean install -DskipTests -Dspotbugs.skip=true
-> ```
+If you haven't already done it, [create and publish the GPG
key](create-gpg-keys.md). You will use the key to sign the release artifacts.
-## Requirements
+Before you start the next release steps, make sure you have installed these
software:
-If you haven't already done it, [create and publish the GPG
key](create-gpg-keys.md) to sign the release artifacts.
+* JDK 11
+* Maven 3.8.6
+* Zip
-Before you start the next release steps, make sure you have installed the
**JDK8** and maven **3.6.1** for Pulsar 2.6 and Pulsar 2.7, and **JDK11** and
Maven **3.6.1** or **3.8.6** for Pulsar 2.8 onwards. And **clean up the
bookkeeper's local compiled** to make sure the bookkeeper dependency is fetched
from the Maven repo, details to see
https://lists.apache.org/thread/gsbh95b2d9xtcg5fmtxpm9k9q6w68gd2
+Also, you need to **clean up the bookkeeper's local compiled** to make sure
the bookkeeper dependency is fetched from the Maven repository, details to see
[this mailing list
thread](https://lists.apache.org/thread/gsbh95b2d9xtcg5fmtxpm9k9q6w68gd2).
-## Create the release branch
+## Create a release candidate
-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.
+### Create the release branch
-The branch needs only to be created when creating major releases,
-and not for minor releases like `2.3.1`. For minor releases, go to the next
step.
+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.
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`.
-In these instructions, I'm referring to a fictitious release `2.X.0`. Change
the release version in the examples accordingly with the real version.
+In these instructions, a fictitious release `2.X.0` is referred. Change the
release version in the examples accordingly with the real version.
It is recommended to create a fresh clone of the repository to avoid any local
files interfering in the process:
@@ -68,20 +67,17 @@ Alternatively, you can use a git workspace to create a new,
clean directory on y
git worktree add ../pulsar.branch-2.X branch-2.X
```
-If you created a new branch, update the `CI - OWASP Dependency Check` workflow
so that it will run on the new branch. At the time of writing, here is the file
that should be updated:
https://github.com/apache/pulsar/blob/master/.github/workflows/ci-owasp-dependency-check.yaml.
+If you created a new branch, update the [CI - OWASP Dependency
Check](https://github.com/apache/pulsar/blob/master/.github/workflows/ci-owasp-dependency-check.yaml)
workflow so that it will run on the new branch.
-Note also that you should stop the GitHub action for Pulsar versions that are
EOL.
+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 `Security Policy and
Supported Versions` page on the website. This page has a table for support
timelines based on when minor releases take place.
+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
+### 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.
+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.
-In this process, the maven version of the project will always
-be the final one.
+In this process, the maven version of the project will always be the final one.
```shell
# Bump to the release version
@@ -109,13 +105,15 @@ git push origin v2.X.0-candidate-1
For minor releases, the tag is like `2.3.1`.
-## Build and inspect the artifacts
+### Build release artifacts
+
+Run the following command to build the artifacts:
```shell
mvn clean install -DskipTests
```
-After the build, there will be 5 generated artifacts and the connectors
directory with all the Pulsar IO nar files:
+After the build, you should find the following tarballs, zip files, and the
connectors directory with all the Pulsar IO nar files:
* `distribution/server/target/apache-pulsar-2.X.0-bin.tar.gz`
* `target/apache-pulsar-2.X.0-src.tar.gz`
@@ -130,54 +128,60 @@ The _apache-pulsar-shell_ artifacts are distributed
beginning with release 2.11.
:::
-Inspect the artifacts:
-* Check that the `LICENSE` and `NOTICE` files cover all included jars for the
-bin package)
- - Use script to cross-validate `LICENSE` file with included jars:
- ```
- src/check-binary-license
distribution/server/target/apache-pulsar-2.x.0-bin.tar.gz
- ```
-* Unpack src package: `target/apache-pulsar-2.X.0-src.tar.gz`
- - Run Apache RAT to verify the license headers in the `src` package:
- ```shell
- cd apache-pulsar-2.X.0
- mvn apache-rat:check
- ```
-* Unpack bin package:
`distribution/server/target/apache-pulsar-2.X.0-bin.tar.gz`, Check that the
standalone Pulsar service starts correctly:
- ```shell
- cd apache-pulsar-2.X.0
- cp -r ../../../io/target/apache-pulsar-io-connectors-2.X.0-bin connectors
- bin/pulsar standalone
- ```
-
-* Use instructions in
[Release-Candidate-Validation](validate-release-candidate.md) to do some sanity
checks on the produced binary distributions.
-
-### Build RPM and DEB packages
+#### Build RPM and DEB packages
+
+For 2.8, 2.9 and 2.10 releases, you should build RPM and DEB packages for the
C++ client:
```shell
pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
-
pulsar-client-cpp/pkg/deb/docker-build-deb.sh
```
-> For 2.11.0 or higher, you can set the environment variable `BUILD_IMAGE` to
build the base image locally instead of pulling from the DockerHub.
-> Since only a few members have the permission to push the image to DockerHub,
the image might not be the latest, if you failed to build the RPM and DEB
packages, you can run `export BUILD_IMAGE=1` before running these commands.
+This will leave the RPM/YUM and DEB repo files in
`pulsar-client-cpp/pkg/rpm/RPMS/x86_64` and
`pulsar-client-cpp/pkg/deb/BUILD/DEB` directory.
-This will leave the RPM/YUM and DEB repo files in
`pulsar-client-cpp/pkg/rpm/RPMS/x86_64` and
-`pulsar-client-cpp/pkg/deb/BUILD/DEB` directory.
+:::note
+
+If you get error `c++: internal compiler error: Killed (program cc1plus)` when
run `pulsar-client-cpp/pkg/deb/docker-build-deb.sh`. You may need to expand
your docker memory greater than 2GB.
-> **NOTE**: If you get error `c++: internal compiler error: Killed (program
cc1plus)` when run `pulsar-client-cpp/pkg/deb/docker-build-deb.sh`. You may
need to expand your docker memory greater than 2GB.
+:::
-## Sign and stage the artifacts
+:::caution
-The `src` and `bin` artifacts need to be signed and uploaded to the dist SVN
-repository for staging.
+The C++ client is now developing in a [separated
repo](https://github.com/apache/pulsar-client-cpp). You should check its own
[release
guide](https://github.com/apache/pulsar-client-cpp/wiki/Committer-Release-Guide)
if you're releasing version >= 3.0.0.
+
+:::
+
+### Inspect the artifacts
+
+First, check that the `LICENSE` and `NOTICE` files cover all included jars for
the bin package. You can use script to cross-validate `LICENSE` file with
included jars:
+
+```shell
+src/check-binary-license
distribution/server/target/apache-pulsar-2.x.0-bin.tar.gz
+```
+
+Then, run Apache RAT to verify the license headers in the src package:
+
+```shell
+tar -xvzf target/apache-pulsar-2.X.0-src.tar.gz
+cd apache-pulsar-2.X.0-src
+mvn apache-rat:check
+```
+
+Finally, use instructions in [verifying release
candidates](validate-release-candidate.md) page to do some sanity checks on the
produced binary distributions.
+
+### Sign and stage the artifacts on SVN
+
+The src and bin artifacts need to be signed and uploaded to the dist SVN
repository for staging.
+
+Before running the script, make sure that the `<yourname>@apache.org` code
signing key is the default gpg signing key.
+
+One way to ensure this is to create/edit file `~/.gnupg/gpg.conf` and add a
line:
-Before running the script, make sure that the `[email protected]` code signing
key is the default gpg signing key.
-One way to ensure this is to create/edit file `~/.gnupg/gpg.conf` and add a
line
```
default-key <key fingerprint>
```
-where `<key fingerprint>` should be replaced with the private key fingerprint
for the `[email protected]` key. The key fingerprint can be found in `gpg -K`
output.
+
+... where `<key fingerprint>` should be replaced with the private key
fingerprint for the `<yourname>@apache.org` key. The key fingerprint can be
found in `gpg -K` output.
```shell
svn co https://dist.apache.org/repos/dist/dev/pulsar pulsar-dist-dev
@@ -194,7 +198,7 @@ svn add *
svn ci -m 'Staging artifacts and signature for Pulsar release 2.X.0'
```
-## Stage artifacts in maven
+### Stage Maven modules
Upload the artifacts to ASF Nexus:
@@ -215,27 +219,21 @@ mvn deploy -DskipTests -Papache-release --settings
/tmp/mvn-apache-settings.xml
mvn deploy -DskipTests -Papache-release --settings
/tmp/mvn-apache-settings.xml -f tests/pom.xml -pl
org.apache.pulsar.tests:tests-parent,org.apache.pulsar.tests:integration
```
-> **NOTE**: The `GPG_TTY` environment variable must be set for all the
following steps. Otherwise, some operations might fail by `gpg failed to sign
the data`.
+:::note
-This will ask for the GPG key passphrase and then upload it to the staging
repository.
+The `GPG_TTY` environment variable must be set for all the following steps.
Otherwise, some operations might fail by "gpg failed to sign the data".
+
+:::
-> If you have deployed before, re-deploying might fail on
pulsar-presto-connector-original.
->
-> See https://github.com/apache/pulsar/issues/17047.
->
-> You can run `mvn clean deploy` instead of `mvn deploy` as a workaround.
+This will ask for the GPG key passphrase and then upload it to the staging
repository.
Log in to the ASF Nexus repository at https://repository.apache.org
-Click on "Staging Repositories" on the left sidebar and then select the current
-Pulsar staging repo. This should be called something like
`orgapachepulsar-XYZ`.
+Click on "Staging Repositories" on the left sidebar and then select the
current Pulsar staging repo. This should be called something like
`orgapachepulsar-XYZ`.
-Use the "Close" button to close the repository. This operation will take few
-minutes. Once complete click "Refresh" and now a link to the staging repository
-should be available, something like
-https://repository.apache.org/content/repositories/orgapachepulsar-XYZ
+Use the "Close" button to close the repository. This operation will take few
minutes. Once complete click "Refresh" and now a link to the staging repository
should be available, something like
https://repository.apache.org/content/repositories/orgapachepulsar-XYZ
-## Publish release candidate docker images
+### Stage Docker images
Run the following commands:
@@ -245,16 +243,16 @@ cd $PULSAR_HOME/docker
DOCKER_USER=<your-username> DOCKER_PASSWORD=<your-password>
DOCKER_ORG=<your-username> ./publish.sh
```
-After that, the following images will be built and pushed to your own
DockerHub account.
-- pulsar
-- pulsar-all
-- pulsar-grafana
-- pulsar-standalone
+After that, the following images will be built and pushed to your own
DockerHub account:
+* pulsar
+* pulsar-all
+* pulsar-grafana
+* pulsar-standalone
-## Run the vote
+## Vote for the release candidate
-Send an email to the Pulsar Dev mailing list:
+Start a voting thread on the dev mailing list. Here is a sample content:
```
To: [email protected]
@@ -298,49 +296,38 @@ Please download the source package, and follow the README
to build
and run the Pulsar standalone service.
```
-The vote should be open for at least 72 hours (3 days). Votes from Pulsar PMC
members
-will be considered binding, while anyone else is encouraged to verify the
release and
-vote as well.
+The vote should be open for at least 72 hours (3 days). Votes from Pulsar PMC
members will be considered binding, while anyone else is encouraged to verify
the release and vote as well.
-If the release is approved here, you can then proceed to the next step.
Otherwise, you should repeat the previous steps and prepare another candidate
release to vote.
+If the release is approved here with 3 +1 binding votes, you can then proceed
to the next step. Otherwise, you should repeat the previous steps and prepare
another release candidate to vote.
-## Move master branch to next version
+## Promote the release
-> **NOTE**: This step is for major releases only.
+### Publish the final tag
-You need to move the master version to the next iteration `Y` (`X + 1`).
+Create and push the final Git tag:
```shell
-git checkout master
-./src/set-project-version.sh 2.Y.0-SNAPSHOT
-
-git commit -m 'Bumped version to 2.Y.0-SNAPSHOT' -a
+git tag -u [email protected] v2.X.0 -m 'Release v2.X.0'
+git push origin v2.X.0
```
-Since this needs to be merged into `master`, you need to follow the regular
process
-and create a Pull Request on GitHub.
+Then, you can [create a GitHub
release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)
based on the tag.
-## Promote the release
+### Release the artifacts on SVN
-Create the final git tag:
+Promote the artifacts on the release SVN repo
https://dist.apache.org/repos/dist/release. Note that this repo is limited to
PMC members, You may need a PMC member's help if you are not one:
```shell
-git tag -u [email protected] v2.X.0 -m 'Release v2.X.0'
-git push origin v2.X.0
+svn move -m "Release Apache Pulsar 2.X.Y" \
+ https://dist.apache.org/repos/dist/dev/pulsar/pulsar-2.X.0-candidate-1 \
+ https://dist.apache.org/repos/dist/release/pulsar/pulsar-2.X.0
```
-Promote the artifacts on the release location(repo
https://dist.apache.org/repos/dist/release limited to PMC, You may need a PMC
member's help if you are not one):
-```shell
-svn move -m "Release Apache Pulsar 2.X.Y"
https://dist.apache.org/repos/dist/dev/pulsar/pulsar-2.X.0-candidate-1 \
- https://dist.apache.org/repos/dist/release/pulsar/pulsar-2.X.0
-```
+### Release Maven modules
-Promote the Maven staging repository for release. Login to
`https://repository.apache.org` and
-select the staging repository associated with the RC candidate that was
approved. The naming
-will be like `orgapachepulsar-XYZ`. Select the repository and click on
"Release". Artifacts
-will now be made available on Maven central.
+Promote the Maven staging repository for release. Login to
`https://repository.apache.org` and select the staging repository associated
with the RC candidate that was approved. The naming will be like
`orgapachepulsar-XYZ`. Select the repository and click on "Release". Artifacts
will now be made available on Maven central.
-## Publish Docker Images
+### Release Docker images
Copy the approved candidate docker images from your personal account to
apachepulsar org.
@@ -358,33 +345,58 @@ done
If you don't have the permission, you can ask someone with access to
apachepulsar org to do that.
-## Release Helm Chart
+### Release Helm Chart
-**This step can be skipped if the major version number is not the latest.**
+:::caution
-1. Bump the image version in the Helm Chart:
[charts/pulsar/values.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/values.yaml)
+This step can be skipped if the major version number is not the latest.
-2. Bump the chart version and `appVersion` in the Helm Chart to the released
version:
[charts/pulsar/Chart.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/Chart.yaml)
+:::
+1. Bump the image version in the Helm Chart:
[charts/pulsar/values.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/values.yaml)
+2. Bump the chart version and `appVersion` in the Helm Chart to the released
version:
[charts/pulsar/Chart.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/Chart.yaml)
3. Send a pull request for reviews and get it merged.
+4. Once it is merged, the chart will be automatically released to GitHub
releases at https://github.com/apache/pulsar-helm-chart and updated to
https://pulsar.apache.org/charts/index.yaml.
+
+### Release Homebrew libpulsar package
-4. Once it is merged, the chart will be automatically released to Github
releases at https://github.com/apache/pulsar-helm-chart and updated to
https://pulsar.apache.org/charts.
+For 2.8, 2.9 and 2.10 releases, you should release the libpulsar package on
Homebrew.
-## Publish Python Clients
+:::caution
+
+The C++ client is now developing in a [separated
repo](https://github.com/apache/pulsar-client-cpp). You should check its own
release guide if you're releasing version >= 3.0.0.
+
+:::
+
+Release a new version of libpulsar for Homebrew, You can follow the example
[here](https://github.com/Homebrew/homebrew-core/pull/53514).
+
+### Release Python client
+
+For 2.8, 2.9 and 2.10 releases, you should release the Python client.
:::note
1. You need to create an account on PyPI: https://pypi.org/account/register/
2. Ask anyone that has been a release manager before to add you as a
maintainer for pulsar-docker on PyPI
-3. Once you have completed the following steps in this section, you can check
if the wheels are uploaded successfully in [Download
files](https://pypi.org/project/pulsar-client/#files). Remember to switch to
the correct version in [Release
history](https://pypi.org/project/pulsar-client/#history)).
+3. Once you have completed the following steps in this section, you can check
if the wheels are uploaded successfully in [Download
files](https://pypi.org/project/pulsar-client/#files). Remember to switch to
the correct version in [Release
history](https://pypi.org/project/pulsar-client/#history).
:::
-### Linux
+:::caution
-There is a script that builds and packages the Python client inside Docker
images.
+Make sure you run following command at the release tag!
-> Make sure you run following command at the release tag!
+:::
+
+:::caution
+
+The Python client is now developing in a [separated
repo](https://github.com/apache/pulsar-client-python). You should check its own
release guide if you're releasing version >= 3.0.0.
+
+:::
+
+#### Linux
+
+There is a script that builds and packages the Python client inside Docker
images:
```shell
pulsar-client-cpp/docker/build-wheels.sh
@@ -392,7 +404,7 @@ pulsar-client-cpp/docker/build-wheels.sh
The wheel files will be left under `pulsar-client-cpp/python/wheelhouse`. Make
sure all the files have `manylinux` in the filenames. Otherwise, those files
will not be able to upload to PyPI.
-Run the following command to push the built wheel files.
+Run the following command to push the built wheel files:
```shell
cd pulsar-client-cpp/python/wheelhouse
@@ -400,113 +412,126 @@ pip install twine
twine upload pulsar_client-*.whl
```
-### MacOS
+#### macOS
-There is a script that builds and packages the Python client inside Docker
images.
+There is a script that builds and packages the Python client inside Docker
images:
```shell
pulsar-client-cpp/python/build-mac-wheels.sh
```
-The wheel files will be generated at each platform directory under
`pulsar-client-cpp/python/pkg/osx/`.
-Then you can run `twin upload` to upload those wheel files.
+The wheel files will be generated at each platform directory under
`pulsar-client-cpp/python/pkg/osx/`. Then you can run `twin upload` to upload
those wheel files.
+
+## Update the document
+
+### Release notes
-## Update Javadocs
+This step is for every release. Read the specific guide for [writing release
notes](release-note-guide.md).
-After publish Java libraries, run the following script from the
apache/pulsar-site `main` branch:
+### Javadoc
+
+:::caution
+
+This step is for major releases only, unless you're sure that significant
Javadoc fixes are made against the minor release.
+
+:::
+
+After publish Java libraries, run the following script from the main branch of
apache/pulsar-site repo:
```shell
cd tools/pytools
poetry install
-poetry run bin/java-apidoc-generator.py 2.11.0
+poetry run bin/java-apidoc-generator.py 2.X.0
```
Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is:
-* `site2/website-next/static/api/admin`
-* `site2/website-next/static/api/client`
-* `site2/website-next/static/api/pulsar-functions`
+* `static/api/admin`
+* `static/api/client`
+* `static/api/pulsar-functions`
Read more on the manual of
[pytools](https://github.com/apache/pulsar-site/tree/main/tools/pytools/README.md).
-## Update config and command-line tool references
+### Reference
+
+:::caution
+
+This step is for major releases only, unless you're sure that significant
Javadoc fixes are made against the minor release.
+
+:::
-Run the following script from the apache/pulsar-site `main` branch:
+You can generate references of config and command-line tool by running the
following script from the main branch of apache/pulsar-site repo:
```shell
-# build Pulsar distributions under /path/to/pulsar-2.11.0
+# build Pulsar distributions under /path/to/pulsar-2.X.0
cd tools/pytools
poetry install
-poetry run bin/bin/reference-doc-generator.py
--master-path=/path/to/pulsar-2.11.0 --version=2.11.0
+poetry run bin/reference-doc-generator.py --master-path=/path/to/pulsar-2.X.0
--version=2.X.0
```
-Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is:
-
-* `site2/website-next/static/api/admin`
-* `site2/website-next/static/api/client`
-* `site2/website-next/static/api/pulsar-functions`
+Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is `static/reference/2.X.x`
Read more on the manual of
[pytools](https://github.com/apache/pulsar-site/tree/main/tools/pytools/README.md).
-## Update C++ client docs
+### C++ client docs
+
+:::caution
+
+This step is for major releases only, unless you're sure that significant
Javadoc fixes are made against the minor release.
-After publishing the C++ client, run the following script from the
apache/pulsar-site `main` branch:
+:::
+
+After publishing the C++ client, run the following script from the main branch
of apache/pulsar-site repo:
```shell
cd tools/pytools
poetry install
-poetry run bin/cpp-apidoc-generator.py 2.11.0
+poetry run bin/cpp-apidoc-generator.py 2.X.0
```
-Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is `site2/website-next/static/api/cpp`.
+Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is `static/api/cpp`.
Read more on the manual of
[pytools](https://github.com/apache/pulsar-site/tree/main/tools/pytools/README.md).
-## Update Python client docs
+### Python client docs
+
+:::caution
+
+This step is for major releases only, unless you're sure that significant
Javadoc fixes are made against the minor release.
-After publishing the Python client, run the following script from the
apache/pulsar-site `main` branch:
+:::
+
+After publishing the Python client, run the following script from the main
branch of apache/pulsar-site repo:
```shell
cd tools/pytools
poetry install
-poetry run bin/py-apidoc-generator.py 2.8.3
+poetry run bin/py-apidoc-generator.py 2.X.0
```
Note that before version 3.0.0, it builds the docs within a docker image, so
you'll need to have docker running.
-Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is `site2/website-next/static/api/python`.
+Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is `static/api/python`.
Read more on the manual of
[pytools](https://github.com/apache/pulsar-site/tree/main/tools/pytools/README.md).
-## Publish Homebrew libpulsar package
+### Swagger files
-**This step can be skipped if the major version number is not the latest.**
-
-Release a new version of libpulsar for Homebrew, You can follow the example
[here](https://github.com/Homebrew/homebrew-core/pull/53514).
+First, build swagger files from apache/pulsar repo at the released tag:
-## Update swagger file
+```shell
+mvn -B -ntp install -Pcore-modules,swagger,-main -DskipTests
-DskipSourceReleaseAssembly=true -Dspotbugs.skip=true -Dlicense.skip=true
+```
-> For major releases, the swagger file update happen under `master` branch,
while for minor releases, swagger file is created from branch-2.x.
+Now, run the following script from the main branch of apache/pulsar-site repo:
```shell
-# ... in the main repo (apache/pulsar)
-cd pulsar
-git checkout branch-2.X
-mvn -am -pl pulsar-broker install -DskipTests -Pswagger
-
-# ... in the site repo (apache/pulsar-site)
-cd pulsar-site
-git checkout -b fix/swagger-file
cd tools/pytools
poetry install
-poetry run bin/rest-apidoc-generator.py --master-path=/path/to/pulsar
--version 2.10.2
+poetry run bin/rest-apidoc-generator.py --master-path=/path/to/pulsar-2.X.Y
--version=2.X.Y
```
-Send out a PR request for review.
-
-## Write release notes
-
-See [Pulsar Release Notes Guide](release-note-guide.md).
+Read more on the manual of
[pytools](https://github.com/apache/pulsar-site/tree/main/tools/pytools/README.md).
## Update the site
@@ -516,18 +541,16 @@ This step is for major releases only.
:::
-For major releases, such as 2.10.0, the website is updated based on the
`master` branch.
-
-1. Create a new branch off master.
+1. Clone the apache/site repo:
```shell
-git checkout -b doc_release_<release-version>
+git clone [email protected]:apache/pulsar-site.git
```
-2. Go to the website directory.
+2. Create a new branch from the main branch.
```shell
-cd site2/website
+git checkout -b doc_release_<release-version>
```
3. Generate a new version of the documentation.
@@ -537,12 +560,7 @@ yarn install
yarn run version <release-version>
```
-After you run this command, a new folder `version-<release-version>` is added
in the `site2/website/versioned_docs` directory, a new sidebar file
`version-<release-version>-sidebars.json` is added in the
`site2/website/versioned_sidebars` directory, and the new version is added in
the `versions.json` file, shown as follows:
-
-```shell
-versioned_docs/version-<release-version>
-versioned_sidebars/version-<release-version>-sidebars.json
-```
+After you run this command, a new folder `version-<release-version>` is added
in the `versioned_docs` directory, a new sidebar file
`version-<release-version>-sidebars.json` is added in the `versioned_sidebars`
directory, and the new version is added in the `versions.json` file.
:::note
@@ -550,32 +568,15 @@ You can move the latest version under the old version in
the `versions.json` fil
:::
-4. Update the `releases.json` file by adding `<release-version>` to the second
of the list (this is to make the search work. After your PR is merged, the
Pulsar website is built and tagged for search, you can change it to the first
list).
-
-5. Send out a PR request for review.
-
- After your PR is approved and merged to master, the website is published
automatically after the new website is built. The website is built every 6
hours.
-
-6. Check the new website after the website is built. Open
https://pulsar.apache.org in your browsers to verify all the changes are alive.
If the website build succeeds but the website is not updated, you can try to
sync the git repository. Navigate to https://selfserve.apache.org/ and click
the "Synchronize Git Repositories" and then select apache/pulsar.
-
-7. Publish the release on GitHub, and copy the same release notes:
https://github.com/apache/pulsar/releases.
-
-8. Update the deploy version to the current release version in
`deployment/terraform-ansible/deploy-pulsar.yaml`.
-
-9. Generate the doc set and sidebar file for the next major release `2.X.x`
based on the `site2/docs` folder. You can follow steps 1, 2, and 3, and submit
those files to the `apache/pulsar` repository. This step is a preparation for
the `2.X.x` release.
-
-:::note
+4. Add `<release-version>` to the corresponding place in the `releases.json`
file.
-Starting from 2.8.0, you don't need to generate an independent doc set or
update the Pulsar site for minor releases, such as 2.8.1, 2.8.2, and so on.
Instead, the generic doc set 2.8.x is used.
+5. Send out a PR request for review. After your PR is approved and merged to
main, the website is published automatically after the new website is built.
The website is built every 6 hours.
-:::note
+6. Check the new website after the website is built. Open
https://pulsar.apache.org in your browsers to verify all the changes are alive.
If the website build succeeds but the website is not updated, you can try to
sync the git repository. Navigate to https://selfserve.apache.org/ and click
the "Synchronize Git Repositories" and then select apache/pulsar-site.
## Announce the release
-Once the release artifacts are available in the Apache Mirrors and the website
is updated,
-we need to announce the release.
-
-Send an email to these lines:
+Once the release artifacts are available in the Apache Mirrors and the website
is updated, you need to announce the release. You should email to
[email protected], [email protected], and [email protected]. Here
is a sample content:
```
To: [email protected], [email protected], [email protected]
@@ -603,19 +604,18 @@ The Pulsar Team
```
Send the email in plain text mode since the [email protected] mailing list
will reject messages with text/html content.
-In Gmail, there's an option to set `Plain text mode` in the `⋮`/ `More
options` menu.
+In Gmail, there's an option to set "Plain text mode" in the "⋮" menu.
+
+## Write a blog post (optional)
-## Write a blog post for the release (optional)
+It is encouraged to write a blog post to summarize the features introduced in
this release, especially for feature releases.
-It is encouraged to write a blog post to summarize the features introduced in
this release,
-especially for feature releases.
-You can follow the example [here](https://github.com/apache/pulsar/pull/2308)
+You can follow the example [here](https://github.com/apache/pulsar/pull/2308).
Be aware that the source of blog is moved to
[here](https://github.com/apache/pulsar-site/tree/main/blog).
## Remove old releases
-Remove the old releases (if any). You only need the latest release there, and
older releases are
-available through the Apache archive:
+Remove the old releases (if any). You only need the latest release there, and
older releases are available through the Apache archive:
```shell
# Get the list of releases
@@ -625,13 +625,20 @@ svn ls https://dist.apache.org/repos/dist/release/pulsar
svn rm https://dist.apache.org/repos/dist/release/pulsar/pulsar-2.Y.0
```
-## Move release branch to next version
+## Move master branch to next version
-Run the following commands in the release branches.
+:::caution
-```shell
-./src/set-project-version.sh 2.X.Y-SNAPSHOT
+This step is for major releases only.
-git commit -m 'Bumped version to 2.X.Y-SNAPSHOT' -a
-git push origin branch-2.X
+:::
+
+You need to move the master version to the next iteration `Y` (`X + 1`).
+
+```shell
+git checkout master
+./src/set-project-version.sh 2.Y.0-SNAPSHOT
+git commit -a -s -m "[cleanup][build] Bumped version to 2.Y.0-SNAPSHOT'
```
+
+Since this needs to be merged into `master`, you need to follow the regular
process and create a Pull Request on GitHub.
diff --git a/contribute/setup-building.md b/contribute/setup-building.md
index 30b948b623d..be78ce5bfa9 100644
--- a/contribute/setup-building.md
+++ b/contribute/setup-building.md
@@ -1,6 +1,6 @@
---
id: setup-building
-title: Setup and Building
+title: Setup and building
---
## Prerequisites
diff --git a/contribute/testing-licenses.md b/contribute/testing-licenses.md
index eef298be99a..bd869411863 100644
--- a/contribute/testing-licenses.md
+++ b/contribute/testing-licenses.md
@@ -1,6 +1,6 @@
---
id: testing-licenses
-title: License Format
+title: License header
---
All code contributed to Pulsar will be licensed under [Apache License
2.0](https://www.apache.org/licenses/LICENSE-2.0). You need to ensure every new
files you are adding have the right license header. You can add license header
to your files by running following command:
diff --git a/contribute/validate-release-candidate.md
b/contribute/validate-release-candidate.md
index 5aae511d721..a81d7b6df2d 100644
--- a/contribute/validate-release-candidate.md
+++ b/contribute/validate-release-candidate.md
@@ -1,6 +1,6 @@
---
id: validate-release-candidate
-title: Validate Release Candidate
+title: Verifying release candidates
---
The following are manual instructions for reviewing and validating a release
candidate.
diff --git a/contribute/version-policy.md b/contribute/version-policy.md
index 09c4df79bc0..945ed500d8a 100644
--- a/contribute/version-policy.md
+++ b/contribute/version-policy.md
@@ -1,6 +1,6 @@
---
id: version-policy
-title: Version Policy
+title: Version policy
---
The Pulsar project adheres to [Semantic
Versioning](http://semver.org/spec/v2.0.0.html). Existing releases can expect
diff --git a/docs/about.md b/docs/about.md
index 6ef50e75471..14ab70fd1eb 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -55,7 +55,7 @@ You’ll notice an Edit button at the bottom and top of each
page. Click it to o
:::tip
-For how to make contributions to documentation, see [Pulsar Documentation
Contribution
Guide](https://github.com/apache/pulsar/blob/master/site2/README.md).
+For how to make contributions to documentation, see [Pulsar Documentation
Contribution Guide](pathname:///contribute/document-intro).
:::
diff --git a/docs/client-libraries.md b/docs/client-libraries.md
index e925bb57065..3d6c72f627c 100644
--- a/docs/client-libraries.md
+++ b/docs/client-libraries.md
@@ -30,7 +30,11 @@ Pulsar client feature matrix for different languages is
listed on [Pulsar Featur
Besides the officially released clients, multiple projects on developing
Pulsar clients are available in different languages.
-> Want your repository listed here? Just submit a PR to the [pulsar
repository](https://github.com/apache/pulsar/edit/master/site2/docs/client-libraries.md).
+:::tip
+
+Want your repository listed here? Click the "Edit this page" button at the
bottom of this page.
+
+:::
### .NET
diff --git a/sidebarsDevelopment.js b/sidebarsDevelopment.js
index 14c1720318f..8a4e71b263b 100644
--- a/sidebarsDevelopment.js
+++ b/sidebarsDevelopment.js
@@ -4,7 +4,7 @@ const sidebars = {
'about',
{
type: "category",
- label: "Getting Started",
+ label: "Getting started",
items: [
'setup-building',
'setup-ide',
@@ -32,8 +32,8 @@ const sidebars = {
items: [
'document-intro',
'document-contribution',
- 'document-syntax',
'document-preview',
+ 'document-syntax',
]
},
{
diff --git a/src/pages/contributing.md b/src/pages/contributing.md
index d21ccd0e311..9994dbb2869 100644
--- a/src/pages/contributing.md
+++ b/src/pages/contributing.md
@@ -373,16 +373,11 @@ For smaller contributions, however, this is not required.
In this case, we rely
### Website
-The Pulsar website is in the same [Pulsar Github
Repo](https://github.com/apache/pulsar). The source files are hosted under
`site2` directory in `master` branch,
-the static content is generated by CI job and merged into the `asf-site`
branch.
-
-Follow the
[README](https://github.com/apache/pulsar-site/tree/main/site2/website-next)
for making contributions to the website.
-
#### Updating user logo
The Apache Pulsar Community welcomes all users to update their company logos
on Pulsar website. If your team or organization has adopted Pulsar in
production, you can update your company logos on [Pulsar
website](https://pulsar.apache.org/en/powered-by/).
To update your company's logo, follow these steps:
-1. Open
[link](https://github.com/apache/pulsar-site/tree/main/site2/website-next/data/users.js)
in your browser, then click the **Edit** icon to fork Pulsar repo, create a
new branch and edit this file.
+1. Open [link](https://github.com/apache/pulsar-site/tree/main/data/users.js)
in your browser, then click the **Edit** icon to fork Pulsar repo, create a new
branch and edit this file.
2. Add your company’s information at the end of file.
Example:
diff --git a/tools/pytools/bin/reference-doc-generator.py
b/tools/pytools/bin/reference-doc-generator.py
index 03ba2004a3e..59a0e091c41 100755
--- a/tools/pytools/bin/reference-doc-generator.py
+++ b/tools/pytools/bin/reference-doc-generator.py
@@ -55,14 +55,15 @@ if __name__ == '__main__':
version = args.version
for kind in kinds:
- match kind:
- case Kind.config:
- config_doc_generator.execute(master_path, version)
- case Kind.admin:
- pulsar_admin_clidoc_generator.execute(master_path, version)
- case Kind.pulsar:
- pulsar_clidoc_generator.execute(master_path, version)
- case Kind.client:
- pulsar_client_clidoc_generator.execute(master_path, version)
- case Kind.perf:
- pulsar_perf_clidoc_generator.execute(master_path, version)
+ if kind == Kind.config:
+ config_doc_generator.execute(master_path, version)
+ elif kind == Kind.admin:
+ pulsar_admin_clidoc_generator.execute(master_path, version)
+ elif kind == Kind.pulsar:
+ pulsar_clidoc_generator.execute(master_path, version)
+ elif kind == Kind.client:
+ pulsar_client_clidoc_generator.execute(master_path, version)
+ elif kind == Kind.perf:
+ pulsar_perf_clidoc_generator.execute(master_path, version)
+ else:
+ raise Exception(f'Unknown reference kind: {kind}')
diff --git a/versioned_docs/version-2.10.x/security-tls-transport.md
b/versioned_docs/version-2.10.x/security-tls-transport.md
index 89851d23576..be4e184311a 100644
--- a/versioned_docs/version-2.10.x/security-tls-transport.md
+++ b/versioned_docs/version-2.10.x/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.2.0/security-tls-transport.md
b/versioned_docs/version-2.2.0/security-tls-transport.md
index 6b289628548..7c3663de151 100644
--- a/versioned_docs/version-2.2.0/security-tls-transport.md
+++ b/versioned_docs/version-2.2.0/security-tls-transport.md
@@ -39,7 +39,7 @@ The following guide is an abridged guide to setting up a
certificate authority.
The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
-Create a directory for your CA, and place [this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and directories needed
for the CA.
+Create a directory for your CA, and place [this openssl configuration
file](pathname:///examples/openssl.cnf) in the directory. You may want to
modify the default answers for company name and department in the configuration
file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest
of the files and directories needed for the CA.
```bash
diff --git a/versioned_docs/version-2.2.1/security-tls-transport.md
b/versioned_docs/version-2.2.1/security-tls-transport.md
index b11c01e97b7..4d1de4512df 100644
--- a/versioned_docs/version-2.2.1/security-tls-transport.md
+++ b/versioned_docs/version-2.2.1/security-tls-transport.md
@@ -39,7 +39,7 @@ The following guide is an abridged guide to setting up a
certificate authority.
The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
-Create a directory for your CA, and place [this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and directories needed
for the CA.
+Create a directory for your CA, and place [this openssl configuration
file](pathname:///examples/openssl.cnf) in the directory. You may want to
modify the default answers for company name and department in the configuration
file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest
of the files and directories needed for the CA.
```bash
diff --git a/versioned_docs/version-2.3.0/security-tls-transport.md
b/versioned_docs/version-2.3.0/security-tls-transport.md
index b11c01e97b7..4d1de4512df 100644
--- a/versioned_docs/version-2.3.0/security-tls-transport.md
+++ b/versioned_docs/version-2.3.0/security-tls-transport.md
@@ -39,7 +39,7 @@ The following guide is an abridged guide to setting up a
certificate authority.
The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
-Create a directory for your CA, and place [this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and directories needed
for the CA.
+Create a directory for your CA, and place [this openssl configuration
file](pathname:///examples/openssl.cnf) in the directory. You may want to
modify the default answers for company name and department in the configuration
file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest
of the files and directories needed for the CA.
```bash
diff --git a/versioned_docs/version-2.3.1/security-tls-transport.md
b/versioned_docs/version-2.3.1/security-tls-transport.md
index b11c01e97b7..4d1de4512df 100644
--- a/versioned_docs/version-2.3.1/security-tls-transport.md
+++ b/versioned_docs/version-2.3.1/security-tls-transport.md
@@ -39,7 +39,7 @@ The following guide is an abridged guide to setting up a
certificate authority.
The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
-Create a directory for your CA, and place [this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and directories needed
for the CA.
+Create a directory for your CA, and place [this openssl configuration
file](pathname:///examples/openssl.cnf) in the directory. You may want to
modify the default answers for company name and department in the configuration
file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest
of the files and directories needed for the CA.
```bash
diff --git a/versioned_docs/version-2.3.2/security-tls-transport.md
b/versioned_docs/version-2.3.2/security-tls-transport.md
index b11c01e97b7..4d1de4512df 100644
--- a/versioned_docs/version-2.3.2/security-tls-transport.md
+++ b/versioned_docs/version-2.3.2/security-tls-transport.md
@@ -39,7 +39,7 @@ The following guide is an abridged guide to setting up a
certificate authority.
The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
-Create a directory for your CA, and place [this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and directories needed
for the CA.
+Create a directory for your CA, and place [this openssl configuration
file](pathname:///examples/openssl.cnf) in the directory. You may want to
modify the default answers for company name and department in the configuration
file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest
of the files and directories needed for the CA.
```bash
diff --git a/versioned_docs/version-2.4.0/security-tls-transport.md
b/versioned_docs/version-2.4.0/security-tls-transport.md
index b11c01e97b7..4d1de4512df 100644
--- a/versioned_docs/version-2.4.0/security-tls-transport.md
+++ b/versioned_docs/version-2.4.0/security-tls-transport.md
@@ -39,7 +39,7 @@ The following guide is an abridged guide to setting up a
certificate authority.
The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
-Create a directory for your CA, and place [this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and directories needed
for the CA.
+Create a directory for your CA, and place [this openssl configuration
file](pathname:///examples/openssl.cnf) in the directory. You may want to
modify the default answers for company name and department in the configuration
file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest
of the files and directories needed for the CA.
```bash
diff --git a/versioned_docs/version-2.4.1/security-tls-transport.md
b/versioned_docs/version-2.4.1/security-tls-transport.md
index b481109c106..f77bcf2cee3 100644
--- a/versioned_docs/version-2.4.1/security-tls-transport.md
+++ b/versioned_docs/version-2.4.1/security-tls-transport.md
@@ -39,7 +39,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.4.2/security-tls-transport.md
b/versioned_docs/version-2.4.2/security-tls-transport.md
index b481109c106..f77bcf2cee3 100644
--- a/versioned_docs/version-2.4.2/security-tls-transport.md
+++ b/versioned_docs/version-2.4.2/security-tls-transport.md
@@ -39,7 +39,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.5.0/security-tls-transport.md
b/versioned_docs/version-2.5.0/security-tls-transport.md
index 09b7db688e7..1bf0256a3de 100644
--- a/versioned_docs/version-2.5.0/security-tls-transport.md
+++ b/versioned_docs/version-2.5.0/security-tls-transport.md
@@ -39,7 +39,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.5.1/security-tls-transport.md
b/versioned_docs/version-2.5.1/security-tls-transport.md
index 45b12501900..172586538d2 100644
--- a/versioned_docs/version-2.5.1/security-tls-transport.md
+++ b/versioned_docs/version-2.5.1/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.5.2/security-tls-transport.md
b/versioned_docs/version-2.5.2/security-tls-transport.md
index 45b12501900..172586538d2 100644
--- a/versioned_docs/version-2.5.2/security-tls-transport.md
+++ b/versioned_docs/version-2.5.2/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.6.0/security-tls-transport.md
b/versioned_docs/version-2.6.0/security-tls-transport.md
index 50552c0a820..c409209900e 100644
--- a/versioned_docs/version-2.6.0/security-tls-transport.md
+++ b/versioned_docs/version-2.6.0/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.6.1/security-tls-transport.md
b/versioned_docs/version-2.6.1/security-tls-transport.md
index 50552c0a820..c409209900e 100644
--- a/versioned_docs/version-2.6.1/security-tls-transport.md
+++ b/versioned_docs/version-2.6.1/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.6.2/security-tls-transport.md
b/versioned_docs/version-2.6.2/security-tls-transport.md
index 50552c0a820..c409209900e 100644
--- a/versioned_docs/version-2.6.2/security-tls-transport.md
+++ b/versioned_docs/version-2.6.2/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.6.3/security-tls-transport.md
b/versioned_docs/version-2.6.3/security-tls-transport.md
index 50552c0a820..c409209900e 100644
--- a/versioned_docs/version-2.6.3/security-tls-transport.md
+++ b/versioned_docs/version-2.6.3/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.6.4/security-tls-transport.md
b/versioned_docs/version-2.6.4/security-tls-transport.md
index 50552c0a820..c409209900e 100644
--- a/versioned_docs/version-2.6.4/security-tls-transport.md
+++ b/versioned_docs/version-2.6.4/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.7.0/security-tls-transport.md
b/versioned_docs/version-2.7.0/security-tls-transport.md
index 57a84ebadb6..9e5633178ff 100644
--- a/versioned_docs/version-2.7.0/security-tls-transport.md
+++ b/versioned_docs/version-2.7.0/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.7.1/security-tls-transport.md
b/versioned_docs/version-2.7.1/security-tls-transport.md
index 57a84ebadb6..9e5633178ff 100644
--- a/versioned_docs/version-2.7.1/security-tls-transport.md
+++ b/versioned_docs/version-2.7.1/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.7.2/security-tls-transport.md
b/versioned_docs/version-2.7.2/security-tls-transport.md
index 57a84ebadb6..9e5633178ff 100644
--- a/versioned_docs/version-2.7.2/security-tls-transport.md
+++ b/versioned_docs/version-2.7.2/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.7.3/security-tls-transport.md
b/versioned_docs/version-2.7.3/security-tls-transport.md
index db8f840d5bc..a107c30d700 100644
--- a/versioned_docs/version-2.7.3/security-tls-transport.md
+++ b/versioned_docs/version-2.7.3/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.7.4/security-tls-transport.md
b/versioned_docs/version-2.7.4/security-tls-transport.md
index db8f840d5bc..a107c30d700 100644
--- a/versioned_docs/version-2.7.4/security-tls-transport.md
+++ b/versioned_docs/version-2.7.4/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.7.5/security-tls-transport.md
b/versioned_docs/version-2.7.5/security-tls-transport.md
index db8f840d5bc..a107c30d700 100644
--- a/versioned_docs/version-2.7.5/security-tls-transport.md
+++ b/versioned_docs/version-2.7.5/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.8.x/security-tls-transport.md
b/versioned_docs/version-2.8.x/security-tls-transport.md
index 127ef2b0018..ecc0d7b13d8 100644
--- a/versioned_docs/version-2.8.x/security-tls-transport.md
+++ b/versioned_docs/version-2.8.x/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
diff --git a/versioned_docs/version-2.9.x/security-tls-transport.md
b/versioned_docs/version-2.9.x/security-tls-transport.md
index 127ef2b0018..ecc0d7b13d8 100644
--- a/versioned_docs/version-2.9.x/security-tls-transport.md
+++ b/versioned_docs/version-2.9.x/security-tls-transport.md
@@ -41,7 +41,7 @@ Follow the guide below to set up a certificate authority. You
can also refer to
1. Create the certificate for the CA. You can use CA to sign both the broker
and client certificates. This ensures that each party will trust the others.
You should store CA in a very secure location (ideally completely disconnected
from networks, air gapped, and fully encrypted).
-2. Entering the following command to create a directory for your CA, and place
[this openssl configuration
file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf)
in the directory. You may want to modify the default answers for company name
and department in the configuration file. Export the location of the CA
directory to the environment variable, CA_HOME. The configuration file uses
this environment variable to find the rest of the files and direc [...]
+2. Entering the following command to create a directory for your CA, and place
[this openssl configuration file](pathname:///examples/openssl.cnf) in the
directory. You may want to modify the default answers for company name and
department in the configuration file. Export the location of the CA directory
to the environment variable, CA_HOME. The configuration file uses this
environment variable to find the rest of the files and directories that the CA
needs.
```bash
