You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ti...@apache.org on 2022/11/16 23:36:20 UTC
[pulsar-site] branch main updated: Refactor contribution guide (#295)
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 2affaf0c176 Refactor contribution guide (#295)
2affaf0c176 is described below
commit 2affaf0c176b0f43ad4be106c2d939d629d8c6d6
Author: tison <wa...@gmail.com>
AuthorDate: Thu Nov 17 07:36:15 2022 +0800
Refactor contribution guide (#295)
Signed-off-by: tison <wa...@gmail.com>
---
site2/tools/pulsar-config-doc-gen.sh | 2 -
.../client-matrix-workflow.png} | Bin
.../obtain-github-permalink.png} | Bin
.../release-note-guide-example.png} | Bin
.../semantic-pull-request-title.png} | Bin
.../preview-2.png => assets/website-preview.png} | Bin
...r-or-pmc-member.md => become-core-developer.md} | 13 +-
.../contribute/committer-guide/_category_.json | 7 -
.../contribute/{releasing => }/create-gpg-keys.md | 3 +-
site2/website-next/contribute/develop-labels.md | 26 +
.../contribute/develop-semantic-title.md | 127 +++++
.../contribute/document-contribution.md | 115 ++++
site2/website-next/contribute/document-intro.md | 37 ++
site2/website-next/contribute/document-preview.md | 100 ++++
site2/website-next/contribute/document-syntax.md | 310 +++++++++++
.../contribute/documentation/_category_.json | 7 -
.../documentation/assets/contribution-1.png | Bin 71797 -> 0 bytes
.../documentation/assets/contribution-2.png | Bin 52487 -> 0 bytes
.../contribute/documentation/assets/preview-1.png | Bin 139893 -> 0 bytes
.../contribute/documentation/assets/syntax-1.png | Bin 160167 -> 0 bytes
.../contribute/documentation/assets/syntax-10.png | Bin 149702 -> 0 bytes
.../contribute/documentation/assets/syntax-11.png | Bin 106124 -> 0 bytes
.../contribute/documentation/assets/syntax-13.png | Bin 172770 -> 0 bytes
.../contribute/documentation/assets/syntax-2.png | Bin 38032 -> 0 bytes
.../contribute/documentation/assets/syntax-3.png | Bin 358193 -> 0 bytes
.../contribute/documentation/assets/syntax-4.png | Bin 243160 -> 0 bytes
.../contribute/documentation/assets/syntax-5.png | Bin 53777 -> 0 bytes
.../contribute/documentation/assets/syntax-6.png | Bin 315928 -> 0 bytes
.../contribute/documentation/assets/syntax-7.png | Bin 83816 -> 0 bytes
.../contribute/documentation/assets/syntax-8.png | Bin 161006 -> 0 bytes
.../contribute/documentation/assets/syntax-9.png | Bin 151067 -> 0 bytes
.../contribute/documentation/contribution.md | 195 -------
.../website-next/contribute/documentation/label.md | 17 -
.../contribute/documentation/naming.md | 173 ------
.../contribute/documentation/overview.md | 38 --
.../contribute/documentation/preview.md | 142 -----
.../contribute/documentation/syntax.md | 258 ---------
.../contribute/getting-started/_category_.json | 7 -
site2/website-next/contribute/personal-ci.md | 50 ++
.../{releasing => }/release-note-guide.md | 25 +-
.../contribute/{releasing => }/release-process.md | 1 -
.../contribute/releasing/_category_.json | 7 -
.../{getting-started => }/setup-building.md | 24 +-
.../contribute/{getting-started => }/setup-ide.md | 61 +--
.../contribute/testing-and-ci/_category_.json | 7 -
.../testing-and-ci/ci-testing-in-fork.md | 63 ---
.../licensing.md => testing-licenses.md} | 5 +-
.../{releasing => }/validate-release-candidate.md | 3 +-
site2/website-next/docusaurus.config.js | 2 +-
site2/website-next/sidebarsContribute.js | 6 -
site2/website-next/sidebarsDevelopment.js | 77 +++
.../config/reference-configuration-bookkeeper.md | 583 +++++++++++++++++++++
.../config/reference-configuration-log4j-shell.md | 37 ++
.../next/config/reference-configuration-log4j.md | 80 +++
.../config/reference-configuration-zookeeper.md | 83 +++
55 files changed, 1688 insertions(+), 1003 deletions(-)
diff --git a/site2/tools/pulsar-config-doc-gen.sh b/site2/tools/pulsar-config-doc-gen.sh
index f11b20ab0db..0002735bd79 100755
--- a/site2/tools/pulsar-config-doc-gen.sh
+++ b/site2/tools/pulsar-config-doc-gen.sh
@@ -38,8 +38,6 @@ CLIENT_CONF=org.apache.pulsar.client.impl.conf
GEN_DOCS_CLIENT=$CLIENT_CONF.CmdGenerateDocumentation
# config doc gen
-cp "$WEBSITE"/docs/reference-configuration*.md "$DOCS_DIR"
-
$JAVA -cp "$(cat "$f")" $GEN_DOCS_BROKER -c org.apache.pulsar.broker.ServiceConfiguration > "$DOCS_DIR"/reference-configuration-broker.md
$JAVA -cp "$(cat "$f")" $GEN_DOCS_BROKER -c org.apache.pulsar.client.impl.conf.ClientConfigurationData > "$DOCS_DIR"/reference-configuration-client.md
$JAVA -cp "$(cat "$f")" $GEN_DOCS_BROKER -c org.apache.pulsar.websocket.service.WebSocketProxyConfiguration > "$DOCS_DIR"/reference-configuration-websocket.md
diff --git a/site2/website-next/contribute/documentation/assets/contribution-3.png b/site2/website-next/contribute/assets/client-matrix-workflow.png
similarity index 100%
rename from site2/website-next/contribute/documentation/assets/contribution-3.png
rename to site2/website-next/contribute/assets/client-matrix-workflow.png
diff --git a/site2/website-next/contribute/documentation/assets/syntax-12.png b/site2/website-next/contribute/assets/obtain-github-permalink.png
similarity index 100%
rename from site2/website-next/contribute/documentation/assets/syntax-12.png
rename to site2/website-next/contribute/assets/obtain-github-permalink.png
diff --git a/site2/website-next/contribute/releasing/release-note-guide-example-1.png b/site2/website-next/contribute/assets/release-note-guide-example.png
similarity index 100%
rename from site2/website-next/contribute/releasing/release-note-guide-example-1.png
rename to site2/website-next/contribute/assets/release-note-guide-example.png
diff --git a/site2/website-next/contribute/documentation/assets/naming-1.png b/site2/website-next/contribute/assets/semantic-pull-request-title.png
similarity index 100%
rename from site2/website-next/contribute/documentation/assets/naming-1.png
rename to site2/website-next/contribute/assets/semantic-pull-request-title.png
diff --git a/site2/website-next/contribute/documentation/assets/preview-2.png b/site2/website-next/contribute/assets/website-preview.png
similarity index 100%
rename from site2/website-next/contribute/documentation/assets/preview-2.png
rename to site2/website-next/contribute/assets/website-preview.png
diff --git a/site2/website-next/contribute/committer-guide/become-a-committer-or-pmc-member.md b/site2/website-next/contribute/become-core-developer.md
similarity index 89%
rename from site2/website-next/contribute/committer-guide/become-a-committer-or-pmc-member.md
rename to site2/website-next/contribute/become-core-developer.md
index f7c63ccb5b0..512cdea18eb 100644
--- a/site2/website-next/contribute/committer-guide/become-a-committer-or-pmc-member.md
+++ b/site2/website-next/contribute/become-core-developer.md
@@ -1,9 +1,14 @@
---
-id: become-a-committer-or-pmc-member
-title: How to Become a Committer or PMC mmeber
-sidebar_label: "How to Become a Committer or PMC mmeber"
+id: become-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).
+
+Basically, core developers consist of committers and PMC members.
+
+## Committers
+
Committers are community members that have write access to the project's repositories, i.e. they can modify the code, documentation, and website by themselves and also accept other contributions.
There is no strict protocol for becoming a committer. Candidates for new committers are typically people that are active contributors and community members.
@@ -18,6 +23,8 @@ Candidates prepare for their nomination as committer by contributing to the Puls
If you would like to become a committer, you should engage with the community and start contributing to Apache Pulsar in any of the above ways. You might also want to talk to other committers and ask for their advice and guidance.
+## PMC Members
+
The project management committee (PMC) is the project governance body. Committers or contributors that have demonstrated continued involvement with the community can be nominated to become members of the PMC.
PMC members nominate new contributors to the project as either committers or as new PMC members, and PMC members cast votes on electing new committers or PMC members to the project. PMC members also have binding votes on any project matters. Refer to [ASF PMCs governance](http://www.apache.org/foundation/governance/pmcs.html) for a more detailed explanation of the duties and roles of the PMC.
diff --git a/site2/website-next/contribute/committer-guide/_category_.json b/site2/website-next/contribute/committer-guide/_category_.json
deleted file mode 100644
index 00dcc986071..00000000000
--- a/site2/website-next/contribute/committer-guide/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
- "label": "Committer Guide",
- "position": 999,
- "link": {
- "type": "generated-index"
- }
-}
diff --git a/site2/website-next/contribute/releasing/create-gpg-keys.md b/site2/website-next/contribute/create-gpg-keys.md
similarity index 98%
rename from site2/website-next/contribute/releasing/create-gpg-keys.md
rename to site2/website-next/contribute/create-gpg-keys.md
index 4c67bb36685..a5fdc8cd12a 100644
--- a/site2/website-next/contribute/releasing/create-gpg-keys.md
+++ b/site2/website-next/contribute/create-gpg-keys.md
@@ -1,14 +1,13 @@
---
id: create-gpg-keys
title: Create GPG keys
-sidebar_label: "Create GPG keys"
---
This page provides instructions for Pulsar committers on how to do the initial GPG setup.
This is a condensed version of instructions available at http://apache.org/dev/openpgp.html.
-Install GnuPG. For example on MacOS:
+Install GnuPG. For example on macOS:
```shell
brew install gnupg
diff --git a/site2/website-next/contribute/develop-labels.md b/site2/website-next/contribute/develop-labels.md
new file mode 100644
index 00000000000..c40caa8bf1e
--- /dev/null
+++ b/site2/website-next/contribute/develop-labels.md
@@ -0,0 +1,26 @@
+---
+id: develop-labels
+title: Labels
+---
+
+This guide explains the labels used in the [apache/pulsar](http://github.com/apache/pulsar) repository (the main repo).
+
+## ready-to-test
+
+After [PR-17693](https://github.com/apache/pulsar/pull/17693) merged, pull requests should be first tested in your own fork since the pulsar CI based on GitHub Actions has constrained resources and quota. GitHub Actions provides separate quota for pull requests that are executed in a forked repository.
+
+When a committer believe the PR is ready to test, they will label `ready-to-test` to the PR, and then you can rerun the CI tasks by commenting `/pulsarbot run-failure-checks` and trigger the full CI validation.
+
+See also [CI Testing in Fork](testing-and-ci/personal-ci.md).
+
+## doc-*
+
+When submitting an issue or PR, you must [choose one of the documentation checkboxes](https://github.com/apache/pulsar/blob/master/.github/PULL_REQUEST_TEMPLATE.md#documentation), so the automation can label the PR correctly.
+
+| Label | Usage |
+|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `doc-not-needed` | Your PR changes do not impact docs |
+| `doc` | Your PR contains doc changes, no matter whether the changes are in markdown or code files. |
+| `doc-required` | Your PR changes impact docs and you will update later. |
+| `doc-complete` | Your PR changes impact docs and the related docs have been already added. |
+| `doc-label-missing` | The Bot applies this label when there is no doc label information in the PR if one of the following conditions is met: <br/><li>You do not provide a doc label.</li><li>You provide multiple doc labels.</li><li>You delete backticks (``) in doc labels.</li><li>You add blanks in square brackets.</li> |
diff --git a/site2/website-next/contribute/develop-semantic-title.md b/site2/website-next/contribute/develop-semantic-title.md
new file mode 100644
index 00000000000..a474b1bc3da
--- /dev/null
+++ b/site2/website-next/contribute/develop-semantic-title.md
@@ -0,0 +1,127 @@
+---
+id: develop-semantic-title
+title: Conventional Commits
+---
+
+This guide explains why you need good PR titles and how you do write PR titles in Conventional Commits spec.
+
+## Why do commit messages matter?
+
+Since the Pulsar community uses "Squash and Merge", the commit message is effectively the same as the PR title.
+
+Engineers and writers submit or review PRs almost every day.
+
+A PR title is a summary of your changes.
+
+* Vague, boring, and unclear PR titles decrease team efficiency and productivity.
+* PR titles should be engaging, easy to understand, and readable.
+
+Good titles often bring many benefits, including but not limited to the following:
+
+* Speed up the review process.
+ * You can tell from the title what changes the PR introduces.
+* Facilitate understanding of PR changes.
+ * PR titles are shown on Pulsar release notes as items. Concise PR titles make your changes easier to understand.
+ * Especially when you read commit logs in command-line tools, clear commit messages show PR changes quickly.
+* Increase search efficiency.
+ * You can skim through hundreds of commits and locate desired information quickly.
+* Remind you to think about your PR.
+ * If you can not write a PR title in a simple way (for example, [[type]](#type), [[scope]](#scope), or [[summary]](#summary)), or you need to use several types/scopes, consider whether your PR contains **too many** changes across various scopes. If so, consider splitting this big PR into several small PRs. In this way, you might get your PRs reviewed faster.
+
+## How to write good PR titles?
+
+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).
+
+### Quick Examples
+
+Here are some examples of unclear and good PR titles for your quick reference. Good PR titles are concise and self-explanatory since they tell you the changes in a clear and direct way.
+
+| Vague (Bad) | Clear (Good) |
+|------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| Producer getting producer busy is removing existing producer from list | [fix][broker] Active producers with the same name are no longer removed from the topic map |
+| Forbid to read other topic's data in managedLedger layer | [improve][broker] Consumers are not allowed to read data on topics to which they are not subscribed |
+| Fix kinesis sink backoff class not found | [improve][connector] xx connectors can now use the Kinesis Backoff class |
+| K8s Function Name Length Check Allows Invalid StatefulSet | [improve][function] Function name length cannot exceed 52 characters when using Kubernetes runtime |
+
+Here are steps to self-review whether the PR title is good:
+
+1. Select a [type](#type).
+2. Select a [scope](#scope).
+3. Write a [summary](#summary).
+
+For more examples with correct formats, see [Full examples](#full-examples).
+
+### Type
+
+`type` is "what actions do you take".
+
+It must be one of the following.
+
+| Type | Label | What actions do you take? |
+|----------|--------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| cleanup | [type/cleanup](https://github.com/apache/pulsar/labels/type%2Fcleanup) | Remove unused code or doc. |
+| improve | [type/improvement](https://github.com/apache/pulsar/labels/type%2Fimprovement) | Submit enhancements that are neither new features nor bug fixes. |
+| feat | [type/feature](https://github.com/apache/pulsar/labels/type%2Ffeature) | Submit new features. |
+| fix | [type/fix](https://github.com/apache/pulsar/labels/type%2Ffix) | Submit bug fixes. |
+| refactor | [type/refactor](https://github.com/apache/pulsar/labels/type%2Frefactor) | Restructure existing code while preserving its external behavior. |
+| revert | N/A | Revert changes |
+
+:::note
+
+Choose correct labels for your PR so that your PR will automatically go to the correct chapter in release notes. If you do not specify a type label, the PR might go to the wrong place or not be included in the release notes at all.
+
+:::
+
+### Scope
+
+`scope` is "where do you make changes".
+
+Scopes evolves along with development. You can check the latest valid scopes at the [workflow file](https://github.com/apache/pulsar/blob/master/.github/workflows/ci-semantic-pull-request.yml).
+
+### Summary
+
+`Summary` is a single line that best sums up the changes made in the commit.
+
+Follow the best practice below:
+
+* Keep the summary concise and descriptive.
+* Use the second person and present tense.
+* Write [complete sentences](https://www.grammarly.com/blog/sentence-fragment) rather than fragments.
+* Capitalize the first letter.
+* Limit the length to 50 characters.
+
+Avoid some common bad cases:
+
+* Do not include back quotes (``).
+* Do not append period at the end.
+* Do not use [GitHub keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) followed by an issue number. This information should be provided in PR descriptions or commit messages rather than in PR titles.
+
+:::note
+
+If you cherry-pick changes to branches, name your PR title the same as the original PR title and label your PR with cherry-pick related labels.
+
+:::
+
+### Full examples
+
+As explained in the [How to write good PR titles](#how-to-write-good-pr-titles) chapter: A good title = clear format ([type](#type) and [scope](#scope)) + self-explanatory [summary](#summary).
+
+Here are some format examples. For self-explanatory summary examples, see [Quick examples](#quick-examples).
+
+| Changes | Unclear format (Bad) | Clear format (Good) |
+|--------------------------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
+| Submit breaking changes | [Breaking change] xxx | [feat][broker]! Support xx |
+| Submit PIP changes | [PIP-198] Support xx | [feat][broker] PIP-198: Support xx |
+| Cherry pick changes | [Branch-2.9] Fix xxx issue. | [fix][broker][branch-2.9] Fix xxx issue |
+| Revert changes | Revert xxx | [revert][broker] Revert changes about xxx |
+| Add features | <li>Adding xx feature</li><li>Support delete schema forcefully</li> | <li>[feat][java client] Add xx feature</li><li>[feat][schema] Support xx</li> |
+| Fix bugs | [Issue 14633][pulsar-broker] Fixed xxx | [fix][broker] Fix xxx |
+| Submit improvements | <li>Enhances xx</li><li>Bump netty version to 4.1.75</li> | <li>[improve][sql] Improve xx performance</li><li>[improve][build] Bump Netty version to 4.1.75</li> |
+| Update tests | reduce xx test flakiness | [improve][test] Reduce xxx flaky tests |
+| Update docs | <li>[Doc] add explanations for xxx</li><li>2.8.3 Release Notes</li><li>Fix typos in xx</li> | <li>[feat][doc] Add explanations for xxx</li><li>[feat][doc] Add 2.8.3 release note</li><li>[fix][doc] Fix typos in xx</li> |
+| Update website | [Website] adjust xxx | [improve][site] Adjust xxx |
+| Update instructions/guidelines | Update xxx guideline | [improve][doc] Update xx guidelines |
diff --git a/site2/website-next/contribute/document-contribution.md b/site2/website-next/contribute/document-contribution.md
new file mode 100644
index 00000000000..0d91ee8145e
--- /dev/null
+++ b/site2/website-next/contribute/document-contribution.md
@@ -0,0 +1,115 @@
+---
+id: document-contribution
+title: Contribution
+---
+
+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 |
+
+## 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.
+
+For versions prior to 2.8, Pulsar releases versioned docs for each patch release. You can update the exact versioned doc.
+
+For versions start from 2.8, Pulsar release versioned docs for each minor release. Apart from updating the content, you should take care of adding specific instructions.
+
+For example, if you want to add docs for an improvement introduced in 2.8.2, you can add the following instructions:
+
+```
+:::note
+
+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.
+
+- 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.
+
+### Update configuration docs
+
+Docs for configs of bundled components are generated from command-line tools **automatically**:
+
+| Components | Update where ... |
+|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Broker | [org.apache.pulsar.broker.ServiceConfiguration](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/ServiceConfiguration.java) |
+| WebSocket | [org.apache.pulsar.websocket.service.WebSocketProxyConfiguration](https://github.com/apache/pulsar/blob/master/pulsar-websocket/src/main/java/org/apache/pulsar/websocket/service/WebSocketProxyConfiguration.java) |
+| Proxy | [org.apache.pulsar.proxy.server.ProxyConfiguration](https://github.com/apache/pulsar/blob/master/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConfiguration.java) |
+| Standalone | [org.apache.pulsar.broker.ServiceConfiguration](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/ServiceConfiguration.java) |
+| Client | [org.apache.pulsar.client.impl.conf.ClientConfigurationData](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ClientConfigurationData.java) |
+| Producer | [org.apache.pulsar.client.impl.conf.ProducerConfigurationData](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ProducerConfigurationData.java) |
+| Consumer | [org.apache.pulsar.client.impl.conf.ConsumerConfigurationData](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ConsumerConfigurationData.java) |
+| Reader | [org.apache.pulsar.client.impl.conf.ReaderConfigurationData](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ReaderConfigurationData.java) |
+
+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) |
+
+### Update command-line tool docs
+
+Docs for bundled Java-based command-line tools are generated **automatically**:
+
+| Components | Update where… |
+|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| pulsar | Different subcommands of [bin/pulsar](https://github.com/apache/pulsar/blob/master/bin/pulsar) are updated in different code files |
+| pulsar-admin | [Classes under the admin command-line folder](https://github.com/apache/pulsar/tree/master/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli) |
+| pulsar-client | [Classes under the client command-line folder](https://github.com/apache/pulsar/tree/master/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli) |
+| pulsar-perf | <li>[The `websocket-producer` subcommand](https://github.com/apache/pulsar/tree/master/pulsar-testclient/src/main/java/org/apache/pulsar/proxy/socket/client)</li><li>[Other subcommands](https://github.com/apache/pulsar/tree/master/pulsar-testclient/src/main/java/org/apache/pulsar/testclient)</li> |
+
+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) |
+
+## Update client/function matrix
+
+[Pulsar Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) outlines every feature supported by the Pulsar client and function.
+
+:::note
+
+* It's public and everyone has access to edit it. You can reach out to `dev@pulsar.apache.org` if you have problems in editing.
+* This matrix will be moved to the Pulsar website (instead of the spreadsheet) in the future.
+
+:::
+
+If you want to update the Pulsar Feature Matrix, follow the steps below.
+
+1. Submit your code and doc PRs.
+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/site2/website-next/contribute/document-intro.md b/site2/website-next/contribute/document-intro.md
new file mode 100644
index 00000000000..974d54984bd
--- /dev/null
+++ b/site2/website-next/contribute/document-intro.md
@@ -0,0 +1,37 @@
+---
+id: document-intro
+title: Introduction
+sidebar_label: "Introduction"
+---
+
+Good documentation is crucial for any kind of software. This is especially true for sophisticated software systems such as distributed messaging system like Apache Pulsar. The Apache Pulsar community aims to provide concise, precise, and complete documentation and welcomes any contribution to improve Apache Pulsar's documentation.
+
+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
+
+* [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
+
+* [Content Preview Guide](document-preview.md)
+
+## Preparing to submit doc PRs
+
+* [Labels](develop-labels.md)
+* [Conventional Commits](develop-semantic-title.md)
+
+## References
+
+In addition, the following resources can help you craft and contribute to docs:
+
+* [Google Technical Writing Courses](https://developers.google.com/tech-writing/overview)
diff --git a/site2/website-next/contribute/document-preview.md b/site2/website-next/contribute/document-preview.md
new file mode 100644
index 00000000000..11f126da01a
--- /dev/null
+++ b/site2/website-next/contribute/document-preview.md
@@ -0,0 +1,100 @@
+---
+id: document-preview
+title: Content Preview
+---
+
+This guide explains why and how to preview Pulsar content locally with detailed steps and various examples.
+
+## Why preview changes locally?
+
+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 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.
+
+### Prerequisites
+
+To verify docs are built correctly before submitting a contribution, you should set up your local environment to build and display the docs locally.
+
+* Node >= 16.14
+* 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 the next version
+ sh start.sh
+ # Preview historical versions
+ sh start.sh [<version-number> ...]
+ ```
+
+3. By default, a browser window will open at http://localhost:3000 to show the changes.
+
+ 
+
+### 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
+
+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/)
+* [Ecosystem page](pathname:///ecosystem)
+* [Case studies page](pathname:///case-studies)
+* ...
+
+Follow these steps to preview the website changes.
+
+1. Change to the working directory:
+
+ ```bash
+ cd pulsar-site/site2/website-next
+ ```
+
+2. Run the following command to preview changes:
+
+ ```bash
+ ./preview.sh 2.10.x # more versions
+ ```
+
+### Stop preview
+
+Switch to your command-line interface and press **Control+C**.
diff --git a/site2/website-next/contribute/document-syntax.md b/site2/website-next/contribute/document-syntax.md
new file mode 100644
index 00000000000..9ecf73cbc8c
--- /dev/null
+++ b/site2/website-next/contribute/document-syntax.md
@@ -0,0 +1,310 @@
+---
+id: document-syntax
+title: Writing Syntax
+---
+
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
+
+This guide explains how to write Pulsar documentation using the MDX-compatible Markdown syntax.
+
+## Background
+
+The Pulsar documentation uses [Markdown](https://www.markdownguide.org/basic-syntax/) as its markup language and [Docusaurus](https://docusaurus.io/) for generating the documentation and website, with [MDX](https://mdxjs.com/) enhancement.
+
+### Why use new Markdown syntax?
+
+The new Pulsar website is upgraded to Docusaurus V2, which uses MDX as the parsing engine. MDX can do much more than just parsing standard Markdown syntax, like rendering React components inside your documents as well.
+
+### How to test doc changes?
+
+You can play with the MDX format in the [MDX Playground](https://mdxjs.com/playground/). Write some MDX to find out what it turns into. You can see the rendered result, the generated code, and the intermediary ASTs. This can be helpful for debugging or exploring.
+
+For how to test doc changes locally, read the [Content Preview Guide](document-preview.md).
+
+## Syntax
+
+This guide just highlights a few selected important rules and frequently used syntax. For the complete syntax guide, read the [Markdown Features](https://docusaurus.io/docs/markdown-features) document from Docusaurus and [Markdown](https://mdxjs.com/docs/what-is-mdx/#markdown) document from MDX.
+
+### Markdown
+
+* Use Markdown rather than HTML as much as possible, or else MDX may not recognize it. For example, when constructing complex tables, do not use `<table>`.
+* Use closing tags. `<li><li/>` and `<br/>` are especially useful for constructing complex tables, such as creating a list and adding a blank line.
+
+#### Example 1
+
+```markdown
+| Directory | Contains |
+|:----------|:------------------------------------|
+| **Hello** | <li>a</li><li>b</li><br/><li>c</li> |
+```
+
+| Directory | Contains |
+|:----------|:------------------------------------|
+| **Hello** | <li>a</li><li>b</li><br/><li>c</li> |
+
+#### Example 2
+
+```markdown
+| a | b | c |
+|-----|-----|--------------------------|
+| aa | bb | cc1<br/>cc2<br/><br/>cc3 |
+```
+
+| a | b | c |
+|-----|-----|--------------------------|
+| aa | bb | cc1<br/>cc2<br/><br/>cc3 |
+
+### Tab
+
+Before using multiple tabs, add these imports at the beginning of the file:
+
+`````markdown
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
+`````
+
+Then, you can write tabs as:
+
+```markdown
+<Tabs>
+ <TabItem value="apple" label="Apple" default>
+ This is an apple 🍎
+ </TabItem>
+ <TabItem value="orange" label="Orange">
+ This is an orange 🍊
+ </TabItem>
+ <TabItem value="banana" label="Banana">
+ This is a banana 🍌
+ </TabItem>
+</Tabs>
+```
+
+<Tabs>
+ <TabItem value="apple" label="Apple" default>
+ This is an apple 🍎
+ </TabItem>
+ <TabItem value="orange" label="Orange">
+ This is an orange 🍊
+ </TabItem>
+ <TabItem value="banana" label="Banana">
+ This is a banana 🍌
+ </TabItem>
+</Tabs>
+
+Read more about how to write multiple tabs at [Tabs](https://docusaurus.io/docs/markdown-features/tabs).
+
+### Code blocks
+
+Read more about how to use syntax highlighting and supported languages at [Syntax highlighting](https://docusaurus.io/docs/markdown-features/code-blocks#syntax-highlighting).
+
+### Admonitions
+
+Docusaurus supports these admonitions:
+
+```markdown
+:::note
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::tip
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::info
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::caution
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::danger
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+```
+
+:::note
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::tip
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::info
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::caution
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+:::danger
+
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+Read more about how to write admonitions at [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions).
+
+### Assets
+
+Static assets are hosted under `/assets` for all documentations:
+
+```markdown
+
+```
+
+### Indentation and space
+
+* Use the same indentation for running texts and code blocks.
+* For the content block after an **ordered list**, indent the content block by only 3 spaces (not 4 spaces).
+* For the content block after an **unordered list**, indent the content block by only 2 spaces.
+* Insert **exact one** empty line (not two empty lines or more) between code blocks and running texts.
+
+:::caution
+
+If you don't insert the empty line, the text cannot be rendered properly. You should encounter an error by [preview](document-preview.md).
+
+:::
+
+### Metadata
+
+If you create a new `.md` file, add quotes for the value of `sidebar_label`.
+
+```yaml
+---
+id: admin-api-partitioned-topics
+title: Managing partitioned topic
+sidebar_label: "Partitioned topics"
+---
+```
+
+If you don't set the `sidebar_label` property, the label is default to `title`.
+
+### Tables
+
+To help tables be easier to maintain, consider adding additional spaces to the column widths to make them consistent. For examples:
+
+```
+| App name | Description | Requirements |
+| :------- | :------------------ | :------------- |
+| App 1 | Description text 1. | Requirements 1 |
+| App 2 | Description text 2. | None |
+```
+
+To format tables easily, you can install a plugin or extension in your editor as below:
+
+* Visual Studio Code: [Markdown Table Prettifier](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify)
+* Sublime Text: [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter)
+* Atom: [Markdown Table Formatter](https://atom.io/packages/markdown-table-formatter)
+
+### Links
+
+Use links instead of summarizing to help preserve a single source of truth in Pulsar documentation.
+
+#### Anchor links
+
+Headings generate anchor links when rendered. For example:
+
+`## This is an example` generates the anchor `#this-is-an-example`.
+
+
+:::caution
+
+* Avoid cross-reference docs to headings unless you need to link to a specific section of the document. This avoids breaking anchors in the future in case the heading is changed.
+* If possible, avoid changing headings, because they're not only linked internally. There are various links to Pulsar documentation on the Internet, such as tutorials, presentations, StackOverflow posts, and other sources.
+
+:::
+
+#### Links to internal documentation
+
+Internal refers to documentation in the same Pulsar project.
+
+General rules:
+
+* Use relative links rather than absolute URLs.
+* Do not prepend `./` or `../../` to links to files or directories.
+
+Examples:
+
+| Scenario | Good | Bad |
+|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Cross-reference to other markdown file (/path/xx/ is not needed) | `[Function overview](function-overview.md)` | <li>`[Function overview](functions-overview)`</li><li>`[Function overview](https://pulsar.apache.org/docs/next/functions-overview/)`</li><li>`[Function overview](../../function-overview.md)`</li> |
+| Cross-reference to other chapters in the same markdown file (# and - are needed) | `[Install builtin connectors (optional)](#install-builtin-connectors-optional)` | N/A |
+
+Read more about how to write Markdown links at [Markdown links](https://docusaurus.io/docs/markdown-features/links).
+
+#### Links to external documentation
+
+When describing interactions with external software, it's often helpful to include links to external documentation. When possible, make sure that you're linking to an [authoritative source](#authoritative-sources).
+
+For example, if you're describing a feature in Microsoft's Active Directory, include a link to the official Microsoft documentation.
+
+#### Link to a specific line of code
+
+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
+
+When citing external information, use sources that are written by the people who created the item or product in question. These sources are the most likely to be accurate and remain up to date.
+
+* ✅ Authoritative sources include the following:
+ * Official documentation for a product.
+
+ For example, if you're setting up an interface with the Google OAuth 2 authorization server, include a link to Google's documentation.
+
+ * Official documentation for a project.
+
+ For example, if you're citing NodeJS functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/).
+
+ * Books from an authoritative publisher.
+
+* ❌ Authoritative sources do not include the following:
+ * Personal blog posts.
+ * Documentation from a company that describes another company's product.
+ * Non-trustworthy articles.
+ * Discussions on forums such as Stack Overflow.
+
+While many of these sources to avoid can help you learn skills and or features, they can become obsolete quickly. Nobody is obliged to maintain any of these sites. Therefore, you should avoid using them as reference literature.
+
+Non-authoritative sources are acceptable only if there is no equivalent authoritative source. Even then, focus on non-authoritative sources that are extensively cited or peer-reviewed.
+
+### Escape
+
+Escape `<` and `>` with back-quote or HTML escape characters.
+
+### Headings
+
+* Each documentation page begins with a **level 2** heading (`##`). This becomes the `<h1>` element when the page is rendered to HTML.
+* Do not skip a level.
+* Leave one blank line before and after the heading.
+* Do not use links as part of heading text.
+* When you change the heading text, the anchor link changes. To avoid broken links:
+ * Do not use step numbers in headings.
+ * When possible, do not use words that might change in the future.
diff --git a/site2/website-next/contribute/documentation/_category_.json b/site2/website-next/contribute/documentation/_category_.json
deleted file mode 100644
index a3fdeed6253..00000000000
--- a/site2/website-next/contribute/documentation/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
- "label": "Documentation",
- "position": 4,
- "link": {
- "type": "generated-index"
- }
-}
diff --git a/site2/website-next/contribute/documentation/assets/contribution-1.png b/site2/website-next/contribute/documentation/assets/contribution-1.png
deleted file mode 100644
index 7363851e8bd..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/contribution-1.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/contribution-2.png b/site2/website-next/contribute/documentation/assets/contribution-2.png
deleted file mode 100644
index 998747a6ef5..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/contribution-2.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/preview-1.png b/site2/website-next/contribute/documentation/assets/preview-1.png
deleted file mode 100644
index 3c60383177f..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/preview-1.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-1.png b/site2/website-next/contribute/documentation/assets/syntax-1.png
deleted file mode 100644
index 17dbb33b4fe..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-1.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-10.png b/site2/website-next/contribute/documentation/assets/syntax-10.png
deleted file mode 100644
index e01122a5ca0..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-10.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-11.png b/site2/website-next/contribute/documentation/assets/syntax-11.png
deleted file mode 100644
index d8ba64d99bd..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-11.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-13.png b/site2/website-next/contribute/documentation/assets/syntax-13.png
deleted file mode 100644
index 56a8cdfd79a..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-13.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-2.png b/site2/website-next/contribute/documentation/assets/syntax-2.png
deleted file mode 100644
index 7a2a11cd1cb..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-2.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-3.png b/site2/website-next/contribute/documentation/assets/syntax-3.png
deleted file mode 100644
index b1026a6eb6d..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-3.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-4.png b/site2/website-next/contribute/documentation/assets/syntax-4.png
deleted file mode 100644
index f13005e39c4..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-4.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-5.png b/site2/website-next/contribute/documentation/assets/syntax-5.png
deleted file mode 100644
index 19cdbfc261c..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-5.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-6.png b/site2/website-next/contribute/documentation/assets/syntax-6.png
deleted file mode 100644
index aec5e6bb13b..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-6.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-7.png b/site2/website-next/contribute/documentation/assets/syntax-7.png
deleted file mode 100644
index 15ad9b013ab..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-7.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-8.png b/site2/website-next/contribute/documentation/assets/syntax-8.png
deleted file mode 100644
index 401222d3278..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-8.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-9.png b/site2/website-next/contribute/documentation/assets/syntax-9.png
deleted file mode 100644
index 6c38d48f8eb..00000000000
Binary files a/site2/website-next/contribute/documentation/assets/syntax-9.png and /dev/null differ
diff --git a/site2/website-next/contribute/documentation/contribution.md b/site2/website-next/contribute/documentation/contribution.md
deleted file mode 100644
index a775d3331bb..00000000000
--- a/site2/website-next/contribute/documentation/contribution.md
+++ /dev/null
@@ -1,195 +0,0 @@
----
-id: contribution
-title: Documentation Contribution Guide
-sidebar_label: "Contribution Guide"
----
-
-This guide explains the organization of Pulsar documentation and website repos and the workflow of updating various Pulsar docs.
-
-## Documentation and website repos
-
-This chapter shows the organization of Pulsar documentation and website repos.
-
-### Intro to doc and website repos
-
-The Pulsar website consists of two parts:
-
-* **Documentation**
-
- Pulsar documentation repo: [pulsar/site2](https://github.com/apache/pulsar/tree/master/site2)
-
- 
-
-* **Website**
-
- Pulsar website repo: [pulsar-site](https://github.com/apache/pulsar-site)
-
- 
-
-### Relationships between doc and website repos
-
-| Type | Repo | Description | PR example [...]
-| ------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
-| Documentation | [pulsar/site2](https://github.com/apache/pulsar/tree/master/site2) | All files related to Pulsar documentation (English) are stored in this repo. | [[feat][doc] add docs for shedding strategy](https://github.com/apache/pulsar/pull/13811) [...]
-| Website | [pulsar-site](https://github.com/apache/pulsar-site) | - All files related to the Pulsar website are stored in the **main** branch in this repo. <br/><br/> - The website is built and put in in the **asf-site-next** branch in this repo. | - [[feat][workflow] add links of doc contribution guides to Pulsar contribution page](https://github.com/apache/pulsar-site/pull/114) <br/><br/> - [[improve][website] add download links for previous versions](https://githu [...]
-
-Files in [pulsar/site2 (master branch)](https://github.com/apache/pulsar/tree/master/site2) are synced to [pulsar-site/website-next (main branch)](https://github.com/apache/pulsar-site/tree/main/site2/website-next) every 6 hours. You can check the sync status and progress at [pulsar-site Actions](https://github.com/apache/pulsar-site/actions/workflows/ci-pulsar-website-docs-sync.yaml).
-
-> **Summary**
->
-> * pulsar/site2/**website** = pulsar-site site2/**website-next**
-> * pulsar/site2/**docs** = pulsar-site/site2/**website-next/docs**
-
-## Update versioned docs
-
-If you want to update versioned docs, go to [pulsar/site2/website/versioned_docs/](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs) to find your desired one.
-
->❗️**BREAKING CHANGE**
->
-> If you want to update docs for 2.8.x and later versions, follow the steps below.
-
-1. Update the correct doc set.
-
- For example, [version-2.8.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.8.x), [version-2.9.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.9.x), or [version-2.10.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.10.x).
-
- For why and how we make this change, see [PIP-190: Simplify documentation release and maintenance strategy](https://github.com/apache/pulsar/issues/16637).
-
-2. Add specific instructions.
-
- For example, if you want to add docs for an improvement introduced in 2.8.2, you can add the following instructions.
-
- ```
- :::note
-
- This <feature / configuration / xx> is available for 2.8.2 and later versions.
-
- :::
- ```
-
-## Update reference docs
-
-If you want to update [Pulsar configuration docs](https://pulsar.apache.org/reference/#/latest/), pay attention to the doc 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 .md files.
-
-### Update Pulsar configuration docs
-
-<table>
- <tr>
- <td><strong>Components</strong>
- </td>
- <td><strong>Update where…</strong>
- </td>
- <td><strong>Notes</strong>
- </td>
- </tr>
- <tr>
- <td>Broker
- </td>
- <td>org.apache.pulsar.broker.ServiceConfiguration
- </td>
- <td rowspan="5" >These components are <strong>internal</strong>.
- <p>These configuration docs are generated from code <strong>automatically</strong></p>.
- </td>
- </tr>
- <tr>
- <td>Client
- </td>
- <td>org.apache.pulsar.client.impl.conf.ClientConfigurationData
- </td>
- </tr>
- <tr>
- <td>WebSocket
- </td>
- <td>org.apache.pulsar.websocket.service.WebSocketProxyConfiguration
- </td>
- </tr>
- <tr>
- <td>Proxy
- </td>
- <td>org.apache.pulsar.proxy.server.ProxyConfiguration
- </td>
- </tr>
- <tr>
- <td>Standalone
- </td>
- <td>org.apache.pulsar.broker.ServiceConfiguration
- </td>
- </tr>
- <tr>
- <td>BookKeeper
- </td>
- <td><a href="https://github.com/apache/pulsar/blob/master/site2/docs/reference-configuration-bookkeeper.md">reference-configuration-bookkeeper.md</a>
- </td>
- <td rowspan="4" >These components are <strong>external</strong>.
- <p>These configuration docs are updated <strong>manually</strong></p>.
- </td>
- </tr>
- <tr>
- <td>Log4j
- </td>
- <td><a href="https://github.com/apache/pulsar/blob/master/site2/docs/reference-configuration-log4j.md">reference-configuration-log4j.md</a>
- </td>
- </tr>
- <tr>
- <td>Log4j shell
- </td>
- <td><a href="https://github.com/apache/pulsar/blob/master/site2/docs/reference-configuration-log4j-shell.md">reference-configuration-log4j-shell.md</a>
- </td>
- </tr>
- <tr>
- <td>ZooKeeper
- </td>
- <td><a href="https://github.com/apache/pulsar/blob/master/site2/docs/reference-configuration-zookeeper.md">reference-configuration-zookeeper.md</a>
- </td>
- </tr>
-</table>
-
-### Update client configuration docs
-
-Pulsar Java configuration docs are generated from code automatically.
-
-| Components | Update where… |
-| ---------- | ------------------------------------------------------------ |
-| Client | org.apache.pulsar.client.impl.conf.ClientConfigurationData |
-| Producer | org.apache.pulsar.client.impl.conf.ProducerConfigurationData |
-| Consumer | org.apache.pulsar.client.impl.conf.ConsumerConfigurationData |
-| Reader | org.apache.pulsar.client.impl.conf.ReaderConfigurationData |
-
-### Update CLI tool docs
-
-| Components | Update where… |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| pulsar-admin | [pulsar/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/](https://github.com/apache/pulsar/tree/master/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli) |
-| pulsar | Different commands are updated in different code files.<br/>Details see [pulsar/bin/pulsar](https://github.com/apache/pulsar/blob/master/bin/pulsar). |
-| pulsar-client | [pulsar/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/](https://github.com/apache/pulsar/tree/master/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli) |
-| pulsar-perf | - `websocket-producer`: [pulsar/pulsar-testclient/src/main/java/org/apache/pulsar/proxy/socket/client/](https://github.com/apache/pulsar/tree/master/pulsar-testclient/src/main/java/org/apache/pulsar/proxy/socket/client)<br/><br/> - Other commands: [pulsar/pulsar-testclient/src/main/java/org/apache/pulsar/testclient/](https://github.com/apache/pulsar/tree/master/pulsar-testclient/src/main/java/org/apache/pulsar/testclient) |
-| pulsar-shell | reference-cli-pulsar-shell.md |
-| pulsar-daemon | reference-cli-pulsar-daemon.md <br/><br/> (It's almost not updated and only contains 3 commands, so it's managed in `md` file rather than being generated automatically) |
-| bookkeeper | reference-cli-bookkeeper.md |
-
-## Update client/function matrix
-
-[Pulsar Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) outlines every feature supported by the Pulsar client and function.
-
-> ❗️ **Note**
->
-> - It’s public and everyone has access to edit it. Feel free to reach out to `liuyu@apache.org` if you have problems in editing.
->
-> - This matrix will be moved to the Pulsar website (instead of the spreadsheet) in the future.
-
-If you want to update the Pulsar Feature Matrix, follow the steps below.
-
-1. Submit your code and doc PRs.
-
-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.
-
- 
-
-## References
-
-For more guides on how to make contributions to Pulsar docs, see [Pulsar Documentation Contribution Overview](./../README.md).
diff --git a/site2/website-next/contribute/documentation/label.md b/site2/website-next/contribute/documentation/label.md
deleted file mode 100644
index 8f170a61fdb..00000000000
--- a/site2/website-next/contribute/documentation/label.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-id: label
-title: Documentation Label Guide
-sidebar_label: "Label Guide"
----
-
-This guide instructs you on how to label your doc PR.
-
-When submitting an issue or PR, you must [provide doc label information](https://github.com/apache/pulsar/blob/master/.github/PULL_REQUEST_TEMPLATE.md#documentation) by **selecting the checkbox**, so that the Bot can label the PR correctly.
-
-| Label | Usage |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `doc-required` | Use this label to indicate this issue or PR impacts documentation.<br/><br/> **You have not updated the docs yet**. The docs will be submitted later. |
-| `doc-not-needed` | The code changes in this PR do not impact documentation. |
-| `doc` | This PR contains changes that impact documentation, **no matter whether the changes are in markdown or code files**. |
-| `doc-complete` | Use this label to indicate the documentation updates are complete. |
-| `doc-label-missing` | The Bot applies this label when there is no doc label information in the PR if one of the following conditions is met:. <br/><br/> - You do not provide a doc label. <br/><br/> - You provide multiple doc labels. <br/><br/> - You delete backticks (``) in doc labels. <br/>For example,<br/> [x] `doc-required` ✅ <br/> [x] doc-required ❌ <br/><br/> - You add blanks in square brackets. <br/>For example, <br/> [x] `doc-required` ✅ <br/>[ x ] `doc-required` ❌ |
diff --git a/site2/website-next/contribute/documentation/naming.md b/site2/website-next/contribute/documentation/naming.md
deleted file mode 100644
index 6d1b7cdd875..00000000000
--- a/site2/website-next/contribute/documentation/naming.md
+++ /dev/null
@@ -1,173 +0,0 @@
----
-id: naming
-title: Pull Request Naming Convention Guide
-sidebar_label: "Naming Convention Guide"
----
-
-This guide explains why you need good PR titles and how you do that with various self-explanatory examples.
-
-
-## Why do PR titles matter?
-
-Engineers and writers submit or review PRs almost every day.
-
-A PR title is a summary of your changes.
-
-* Vague, boring, and unclear PR titles decrease team efficiency and productivity.
-* PR titles should be engaging, easy to understand, and readable.
-
-Good titles often bring many benefits, including but not limited to the following:
-
-* Speed up the review process.
- * You can tell from the title what changes the PR introduces.
-* Facilitate understanding of PR changes.
- * PR titles are shown on Pulsar release notes as items. Concise PR titles make your changes easier to understand.
- * Especially when you read commit logs in command-line tools, clear commit messages show PR changes quickly.
-* Increase search efficiency.
- * You can skim through hundreds of commits and locate desired information quickly.
-* Remind you to think about your PR.
- * If you can not write a PR title in a simple way (for example, [[type]](#type) [[scope]](#scope) [[summary]](#summary)), or you need to use several types / scopes, consider whether your PR contains **too many** changes across various scopes. If so, consider splitting this big PR into several small PRs. In this way, you might get your PRs reviewed faster.
-
-## How to write good PR titles?
-
-A PR title should be structured as follows:
-
-
-
-
-> 💡 **Rule**
->
-> A good title = clear format ([type](#type) and [scope](#scope)) + self-explanatory [summary](#summary)
-
-
-### 💡Quick examples
-
-Here are some examples of unclear and good PR titles for your quick reference. Good PR titles are concise and self-explanatory since they tell you the changes in a clear and direct way.
-
-For more examples with correct formats, see [Full examples](#full-examples).
-
-🙌 **Examples**
-
-| Vague ❌ | Clear ✅ |
-| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| Producer getting producer busy is removing existing producer from list | [fix][broker] Active producers with the same name are no longer removed from the topic map |
-| Forbid to read other topic's data in managedLedger layer | [improve][broker] Consumers are not allowed to read data on topics to which they are not subscribed |
-| Fix kinesis sink backoff class not found | [improve][connector] xx connectors can now use the Kinesis Backoff class |
-| K8s Function Name Length Check Allows Invalid StatefulSet | [improve][function] Function name length cannot exceed 52 characters when using Kubernetes runtime |
-
-> 💡 **Steps**
->
-> How to write a good PR title?
->
-> 1. Select a [type](#type).
-> 2. Select a [scope](#scope).
-> 3. Write a [summary](#summary).
-
-### `type`
-
-`type` is "what actions do you take".
-
-It must be one of the following.
-
-| type | Pulsar PR label | What actions do you take? |
-| -------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
-| cleanup | [type/cleanup](https://github.com/apache/pulsar/labels/type%2Fcleanup) | Remove unused code or doc. |
-| improve | [type/improvement](https://github.com/apache/pulsar/labels/type%2Fimprovement) | Submit enhancements that are neither new features nor bug fixes. |
-| feat | [type/feature](https://github.com/apache/pulsar/labels/type%2Ffeature) | Submit new features. |
-| fix | [type/fix](https://github.com/apache/pulsar/labels/type%2Ffix) | Submit bug fixes. |
-| refactor | [type/refactor](https://github.com/apache/pulsar/labels/type%2Frefactor) | Restructure existing code while preserving its external behavior. |
-| revert | To be created | Revert changes |
-
->❗️ **Note**
->
-> - Choose correct labels for your PR so that your PR will automatically go to the correct chapter in release notes. If you do not specify a type label, the PR might go to the wrong place or not be included in the release notes at all.
->
-> - For more information about release note automation for Pulsar and clients, see [PIP 112: Generate Release Notes Automatically](https://docs.google.com/document/d/1Ul2qIChDe8QDlDwJBICq1VviYZhdk1djKJJC5wXAGsI/edit).
-
-### `scope`
-
-`scope` is "where do you make changes".
-
-Pulsar and clients have separate release notes, so they have different scopes.
-
->❗️ **Note**
->
-> If your PR affects several scopes, do not choose several scope labels at the same time since different scopes go to different chapters in release notes. Instead, choose the most affected label (scope), or else your PR goes to several chapters in release notes, which causes redundancies. Choose only one label as much as possible.
-
-#### Pulsar
-
-`scope` and PR labels must be one of the following.
-
-| scope | Pulsar PR label | Where do you make changes? |
-| --------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| admin | - scope/admin <br/>- scope/topic-policy | - pulsar-admin <br/> - REST API <br/> - Java admin API |
-| broker | - scope/broker | It’s difficult to maintain an exhaustive list since many changes belong to brokers. <br/><br/> Here just lists some frequently updated areas, it includes but not limited to:<br/> - key_shared <br/> - replication <br/> - metadata <br/> - compaction |
-| cli | - scope/tool | Pulsar CLI tools. <br/> It includes: <br/> - pulsar <br/> - pulsar-client <br/> - pulsar-daemon <br/> - pulsar-perf <br/> - bookkeeper<br/> - broker-tool |
-| io<br/>(connector) | - scope/connector <br/> - scope/connect <br/> - scope/kafka | Connector |
-| fn<br/>(function) | - scope/function | Function |
-| meta<br/>(metadata) | - scope/zookeepeer | Metadata |
-| monitor | - scope/metrics - scope/stats | Monitoring |
-| proxy | - scope/proxy | Proxy |
-| schema | - scope/schema <br/> - scope/schemaregistry | Schema |
-| sec<br/>(security) | - scope/security <br/> - scope/authentication <br/> - scope/authorization | Security |
-| sql | - scope/sql | Pulsar SQL |
-| storage | - scope/bookkeeper storage | Managed ledge |
-| offload<br/>(tiered storage) | - scope/tieredstorage | Tiered storage |
-| txn | - scope/transaction<br/> - scope/transaction-coordinator | Transaction |
-| test | - scope/test | Code tests |
-| ci | - scope/ci | CI workflow changes or debugging |
-| build | - scope/build | - Dependency (Maven) <br/> - Docker <br/> - Build or release script |
-| misc | - scope/misc | Changes that do not belong to any scopes above. |
-| doc | - doc | Documentation |
-| site<br/>(website) | - website | Website |
-
-#### Client
-
-The following changes are shown on the client release notes.
-
-`scope` and PR label must be one of the following.
-
-| scope | Pulsar PR label | Where do you make changes? |
-| ----------------------- | ---------------------- | -------------------------------------------------------------------------------- |
-| client<br/>(Java client) | scope/client-java | Java client |
-| ws<br/>(WebSocket) | scope/client-websocket | [WebSocket API](https://pulsar.apache.org/docs/next/client-libraries-websocket/) |
-
-### `Summary`
-
-`Summary` is a single line that best sums up the changes made in the commit.
-
-Follow the best practice below:
-
-* Keep the summary concise and descriptive.
-* Use the second person and present tense.
-* Write [complete sentences](https://www.grammarly.com/blog/sentence-fragment/#:~:text=What's%20a%20sentence%20fragment%3F,%2C%20a%20verb%2C%20or%20both.) rather than fragments.
-* Capitalize the first letter.
-* No period at the end. ❌
-* Do not include back quotes (``).
-* Limit the length to 50 characters.
-* If you cherry pick changes to branches, name your PR title the same as the original PR title and label your PR with cherry-pick related labels.
-* Do not use [GitHub keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) followed by a #<issue-number>. This information should be provided in PR descriptions or commit messages rather than in PR titles. ❌
-
-### Full examples
-
-As explained in the [How to write good PR titles](#how-to-write-good-pr-titles) chapter:
-
-> 💡 **Rule**
->
-> A good title = clear format ([type](#type) and [scope](#scope)) + self-explanatory [summary](#summary)
-
-Here are some format examples. For self-explanatory summary examples, see [Quick examples](#quick-examples).
-
-| Changes | Unclear format ❌ | Clear format ✅ |
-| ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Submit breaking changes | [Breaking change] xxx | [feat][broker]! Support xx |
-| Submit PIP changes | [PIP-198] Support xx | [feat][broker] PIP-198: Support xx |
-| Cherry pick changes | [Branch-2.9] Fix xxx issue. | [fix][broker][branch-2.9] Fix xxx issue |
-| Revert changes | Revert xxx | [revert][broker] Revert changes about xxx |
-| Add features | - Adding xx feature <br/> - Support delete schema forcefully | - [feat][java client] Add xx feature <br/> - [feat][schema] Support xx |
-| Fix bugs | [Issue 14633][pulsar-broker] Fixed xxx | [fix][broker] Fix xxx |
-| Submit improvements | - Enhances xx <br/> - Bump netty version to 4.1.75 | - [improve][sql] Improve xx performance <br/> - [improve][build] Bump Netty version to 4.1.75 |
-| Update tests | reduce xx test flakiness | [improve][test] Reduce xxx flaky tests |
-| Update docs | - [Doc] add explanations for xxx <br/> - 2.8.3 Release Notes <br/> - Fix typos in xx | - [feat][doc] Add explanations for xxx <br/> - [feat][doc] Add 2.8.3 release note <br/> - [fix][doc] Fix typos in xx |
-| Update website | [Website] adjust xxx | [improve][site] Adjust xxx |
-| Update instructions/guidelines | Update xxx guideline | [improve][doc] Update xx guidelines |
diff --git a/site2/website-next/contribute/documentation/overview.md b/site2/website-next/contribute/documentation/overview.md
deleted file mode 100644
index ee6c615ba6c..00000000000
--- a/site2/website-next/contribute/documentation/overview.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: overview
-title: Documentation Contribution Overview
-sidebar_label: "Overview"
-sidebar_position: 1
----
-
-As you start your Pulsar journey, you might don’t understand something or make mistakes. Don’t worry and take it easy. The Pulsar community is a joint effort based on respect, openness, friendliness, discussions, and consensus. Everyone is encouraged to contribute and any help is appreciated!
-
-The **Pulsar Documentation Contribution Overview** 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 docs
-
-* [Pulsar Documentation Contribution Guide](contribution.md)
- * Doc structure and project organization
- * Workflow of submitting various docs
-
-## Writing docs
-
-* [Pulsar Documentation Writing Syntax Guide](syntax.md)
-* [Pulsar Documentation Writing Style Guide](https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#)
-* [Pulsar Design Style Guide](https://docs.google.com/document/d/16Hp7Sc86MQtL0m8fc2w_TrcKXAuglwRwHmdmwfk00mI/edit#heading=h.b8ogodj5sj0)
-* [Pulsar API Documentation Guide](https://docs.google.com/document/d/1-I1oQp1_HUaQopqilU-JdC-ksrLAgYNi93FZVnECwV8/edit#heading=h.wu6ygjne8e35)
-
-## Testing docs
-
-* [Pulsar Content Preview Guide](preview.md)
-
-## Preparing to submit doc PRs
-
-* [Pulsar Pull Request Naming Convention Guide](naming.md)
-* [Pulsar Documentation Label Guide](label.md)
-
-## References
-
-In addition, the following resources can help you craft and contribute to docs:
-
-* [Google Technical Writing Courses](https://developers.google.com/tech-writing/overview)
diff --git a/site2/website-next/contribute/documentation/preview.md b/site2/website-next/contribute/documentation/preview.md
deleted file mode 100644
index e0b9ac3d9aa..00000000000
--- a/site2/website-next/contribute/documentation/preview.md
+++ /dev/null
@@ -1,142 +0,0 @@
----
-id: preview
-title: Content Preview Guide
-sidebar_label: "Content Preview Guide"
----
-
-This guide explains why and how to preview Pulsar content locally with detailed steps and various examples.
-
-## Why preview changes locally?
-
-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 [Pulsar Documentation Writing Syntax](./syntax.md) and debug issues. 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.
-
-### Prerequisites
-
-To verify docs are built correctly before submitting a contribution, you should set up your local environment to build and display the docs locally.
-
-* Node >= 16.14
-
-* 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 doc (markdown) changes
-
-Follow these steps to build the doc (markdown) preview on your local machine.
-
-1. Go to the correct repo.
-
- ```bash
- cd pulsar/site2/website
- ```
-
-2. Run the following command to preview changes.
-
-* Preview **master** changes
-
- If you update master docs, use the following command.
-
- ```bash
- sh start.sh
- ```
-
-* Preview **historical** changes
-
- If you update versioned docs, use the following command.
-
- It may take a few more minutes to complete the process.
-
- ```bash
- sh start.sh <version-number> <version-number>
- ```
-
- 
-
-3. By default, a browser window will open at http://localhost:3000 to show the changes.
-
- 
-
-### Preview doc (Java API) changes
-
-Follow these steps to build the doc (Java API) preview on your local machine on the **master** branch.
-
-1. Go to the correct repo.
-
- ```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.
-
- For example, if you change the [ConsumerBuilder.java](http://pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java) for [Pulsar Java docs](https://pulsar.apache.org/api/client/2.11.0/org/apache/pulsar/client/api/ConsumerBuilder.html), you can navigate to the `generated-site/api/client/{version}/org/apache/pulsar/client/api/` directory and open the `ConsumerBuilder.html` file to preview the updates.
-
-### Preview website 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](https://pulsar.apache.org/release-notes/) ✅
-* [Ecosystem page](https://pulsar.apache.org/ecosystem) ✅
-* [Case studies page](https://pulsar.apache.org/case-studies) ✅
-* …
-* (except docs ❌)
-
-Follow these steps to build the website preview on your local machine.
-
-1. Go to the correct repo.
-
- ```bash
- cd pulsar-site/site2/website-next
- ```
-
-2️. Run the following command to preview changes.
-
- * Preview **master** changes
-
- If you submit changes to master, use the following command.
-
- ```bash
- ./preview.sh
- ```
-
- * Preview **historical** changes
-
- ```bash
- ./preview.sh <version-number> <version-number> …
- ```
-
- > ❗️ **Note**
- >
- > * Use a space between `<version-number> <version-number>`.
- >
- > * If you want to preview multiple version changes, append `<version-number>` with blanks.
- >
- > For example, `./preview.sh 2.9.1 2.9.2 2.9.3`.
-
-### Stop preview
-
-If you want to stop the preview, use one of the following methods.
-
-* Method 1: Switch to your command-line interface and press **Control+C**.
-* Method 2: Switch to your browser and close the preview page.
-
-### Maintenance info
-
-* For the old Pulsar website, using ` yarn start` can preview all (master + historical) changes. However, to speed up the build process, for the new Pulsar website, using `./preview.sh `only preview master changes.
diff --git a/site2/website-next/contribute/documentation/syntax.md b/site2/website-next/contribute/documentation/syntax.md
deleted file mode 100644
index c6af3a20174..00000000000
--- a/site2/website-next/contribute/documentation/syntax.md
+++ /dev/null
@@ -1,258 +0,0 @@
----
-id: syntax
-title: Documentation Writing Syntax Guide
-sidebar_label: "Writing Syntax Guide"
----
-
-This guide explains how to write Pulsar documentation using the MDX-compatible markdown syntax.
-
-## Background
-
-The Pulsar documentation uses [Markdown](https://www.markdownguide.org/basic-syntax/) as its markup language and [Docusaurus](https://docusaurus.io/) for generating the documentation and website.
-
-> 🔴 **BREAKING CHANGE**
->
-> From 2022/5/18, you need to use **Markdown syntax that is compatible with MDX**. Otherwise, your changes can not be recognized by MDX and rendered properly. In this case, your PR can not be merged.
-
-### Why use new markdown syntax?
-
-The new Pulsar website is launched on 2022/5/11. It is upgraded to Docusaurus V2, which uses MDX as the parsing engine. MDX can do much more than just parsing standard Markdown syntax, like rendering React components inside your documents as well. However, **some previous documentation using Markdown syntax is incompatible with MDX**。 Consequently, you need to change the way you write.
-
-### How to test doc changes?
-
-- You can play with the MDX format in **[MDX Playground](https://mdxjs.com/playground/)** . Write some MDX to find out what it turns into. You can see the rendered result, the generated code, and the intermediary ASTs. This can be helpful for debugging or exploring.
-
-- For how to test doc changes locally, see [Pulsar Content Preview Guide](./preview.md).
-
-## Syntax
-
-> ❗️**Note**
->
-> This guide just highlights **some** important rules and frequently used syntax that is **different from the Markdown syntax used in the previous docs**. For the complete syntax guide, see [Docusaurus - Markdown Features](https://docusaurus.io/docs/next/markdown-features) and [MDX - Markdown](https://mdxjs.com/docs/what-is-mdx/#markdown).
-
-### Markdown
-
-* **Use Markdown rather than HTML** as much as possible, or else MDX may not recognize it.
-
- For example, when constructing complex tables, do not use HTML (`<table>`).
-
-* Use **closing** tags.
-
- `<li></li>` and `<br/></br>` are especially useful for constructing complex tables, such as _creating a list_ and _adding a blank line_.
-
- 🙌 **Examples**
-
- ```
- <li>xxx ❌
- <br/>xxx ❌
- <li>xxx</li> ✅
- ```
-
- 
-
- ```
- <br />xxx → wrap text in "next" line ✅
- <br /><br />xxx → wrap text in "next next" line ✅
- ```
-
- 
-
-* If you need to use HTML, use **React** syntax for HTML tags.
-
- 🙌 **Examples**
-
- ```
- <span style="color: #bb3b3e;"></span> ❌
-
- <span style={{color: "#bb3b3e"}}>deleted</span> ✅
- ```
-
-### Tab
-
-The image below shows the differences in writing multiple tabs before and after. For how to write multiple tabs, see [Tabs](https://docusaurus.io/docs/next/markdown-features/tabs).
-
-
-
-### Code blocks
-
-For how to use syntax highlighting and supported languages, see [Syntax highlighting](https://docusaurus.io/docs/next/markdown-features/code-blocks#syntax-highlighting).
-
-### Admonitions
-
-The image below shows the differences to write admonitions before and after.
-
-For how to write admonitions, see [Admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions).
-
-
-
-### Assets
-
-Add dash `/` before the asset path.
-
-🙌 **Examples**
-
-```
-
-```
-
-### Indentation & space
-
-* Use the same indentation for running texts and code blocks.
-
- 🙌 **Examples**
-
- 
-
-
-* For the content block after an **ordered list**, indent the content block by only 3 spaces (not 4 spaces).
-
-* For the content block after an **unordered list**, indent the content block by only 2 spaces.
-
- 🙌 **Examples**
-
- 
-
- > 💡 **Tip**
- >
- > You can set the **Tab Size** in VS Code settings.
- >
- > 
-
-* Insert **only an** empty line (not two empty lines or more) between code blocks and running texts.
-
- 🙌 **Examples**
-
- 
-
- 
-
- 
-
-### Metadata
-
-If you create a new `.md` file, add quotes for the value of sidebar_label.
-
-🙌 **Examples**
-
-
-
-### Tables
-
-To help tables be easier to maintain, consider adding additional spaces to the column widths to make them consistent.
-
-🙌 **Examples**
-
-```
-| App name | Description | Requirements |
-| :------- | :------------------ | :------------- |
-| App 1 | Description text 1. | Requirements 1 |
-| App 2 | Description text 2. | None |
-```
-
-To format tables easily, you can install a plugin or extension in your editor as below:
-
-* Visual Studio Code: [Markdown Table Prettifier](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify)
-
-* Sublime Text: [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter)
-
-* Atom: [Markdown Table Formatter](https://atom.io/packages/markdown-table-formatter)
-
-### Links
-
-Use links instead of summarizing to help preserve a single source of truth in Pulsar documentation.
-
-#### Anchor links
-
-Headings generate anchor links when rendered.
-
-🙌 **Examples**
-
-`## This is an example` generates the anchor `#this-is-an-example`.
-
-> ❗️ **Note**
->
-> * Avoid crosslinking docs to headings unless you need to link to a specific section of the document. This avoids breaking anchors in the future in case the heading is changed.
->
-> * If possible, avoid changing headings, because they’re not only linked internally. There are various links to Pulsar documentation on the internet, such as tutorials, presentations, StackOverflow posts, and other sources.
-
-#### Links to internal documentation
-
-Internal refers to documentation in the same Pulsar project.
-
-General rules:
-
-* Use relative links rather than absolute URLs.
-
-* Don’t prepend ./ or ../../ to links to files or directories.
-
-🙌 **Examples**
-
-| Scenario | ✅ | ❌ |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Crosslink to other markdown file <br/><br/> (/path/xx/ is not needed) | `[Function overview](function-overview.md)` | - `[Function overview](functions-overview)` <br/><br/> - `[Function overview](https://pulsar.apache.org/docs/next/functions-overview/)` <br/><br/> - `[Function overview](../../function-overview.md)` |
-| Crosslink to other chapters in the same markdown file <br/><br/> (# and - are needed) | `[Install builtin connectors (optional)](#install-builtin-connectors-optional)` | N/A |
-
-#### Links to external documentation
-
-When describing interactions with external software, it’s often helpful to include links to external documentation. When possible, make sure that you’re linking to an [authoritative source](#authoritative-sources).
-
-For example, if you’re describing a feature in Microsoft’s Active Directory, include a link to official Microsoft documentation.
-
-#### Link to a specific line of code
-
-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
-
-When citing external information, use sources that are written by the people who created the item or product in question. These sources are the most likely to be accurate and remain up to date.
-
-🙌 **Examples**
-
-- Authoritative sources include the following ✅
-
- * Official documentation for a product.
-
- For example, if you’re setting up an interface with the Google OAuth 2 authorization server, include a link to Google’s documentation.
-
- * Official documentation for a project.
-
- For example, if you’re citing NodeJS functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/).
-
- * Books from an authoritative publisher.
-
-- Authoritative sources do not include the following ❌
-
- * Personal blog posts.
-
- * Documentation from a company that describes another company’s product.
-
- * Non-trustworthy articles.
-
- * Discussions on forums such as Stack Overflow.
-
-While many of these sources to avoid can help you learn skills and or features, they can become obsolete quickly. Nobody is obliged to maintain any of these sites. Therefore, we should avoid using them as reference literature.
-
-Non-authoritative sources are acceptable only if there is no equivalent authoritative source. Even then, focus on non-authoritative sources that are extensively cited or peer-reviewed.
-
-### Escape
-
-Use the following characters to escape special characters.
-
-🙌 **Examples**
-
-| ✅ | ❌ |
-| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `List<String>` <br/><br/>This error shows up  | List`<String>`<br/><br/>Here is an [example PR](https://github.com/apache/pulsar/pull/15389/files#diff-472b2cb6fc28a0845d2f1d397dc4e6e7fa083dfe4f91d6f9dca88ad01d06a971). |
-
-
-### Headings
-
-* Each documentation page begins with a **level 2** heading (##). This becomes the h1 element when the page is rendered to HTML.
-* Do not skip a level. For example: ## > ####.
-* Leave one blank line before and after the heading.
-* Do not use links as part of heading text.
-* When you change the heading text, the anchor link changes. To avoid broken links:
- * Do not use step numbers in headings.
- * When possible, do not use words that might change in the future.
diff --git a/site2/website-next/contribute/getting-started/_category_.json b/site2/website-next/contribute/getting-started/_category_.json
deleted file mode 100644
index 1670452b96b..00000000000
--- a/site2/website-next/contribute/getting-started/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
- "label": "Getting Started",
- "position": 3,
- "link": {
- "type": "generated-index"
- }
-}
diff --git a/site2/website-next/contribute/personal-ci.md b/site2/website-next/contribute/personal-ci.md
new file mode 100644
index 00000000000..52c9ac0ba06
--- /dev/null
+++ b/site2/website-next/contribute/personal-ci.md
@@ -0,0 +1,50 @@
+---
+id: personal-ci
+title: Personal CI
+---
+
+Pulsar CI is currently hosted on Apache Infra resources. Since we cannot add more resources to Pulsar CI, we need to find other ways to reduce the load on Pulsar CI.
+
+After [PR-17693](https://github.com/apache/pulsar/pull/17693) merged, any pull request directly sent to `apache/pulsar` won't be triggered anymore.
+
+That said, pull requests should be first tested in your own fork. GitHub Actions provides separate quota for pull requests that are executed in a forked repository.
+
+## CI workflows in a fork
+
+Here are instructions to use your personal CI on GitHub:
+
+1. Push your intended pull request changes to a new branch in your fork (the usual way you do it).
+2. Open a pull request to your own fork.
+
+Below are the instructions for command-line interface.
+
+Firstly, install [GitHub CLI](https://cli.github.com/) and configure it. With GitHub CLI, there's an easy way to open the PR to your own fork with a single command:
+
+```bash
+gh pr create --repo=<your-github-id>/pulsar --base master --head <your-pr-branch> -f
+```
+
+Alternatively, you can also create a PR to your own fork in the GitHub UI when opening a new PR. To do so, first click on "compare across forks" and then choose your own fork as both the forked repository and head repository.
+
+## Stay in-sync with upstream
+
+It's worth keeping your master branch in sync with apache/pulsar's master (the upstream) so that the diff of PR will be reasonable in your own fork.
+
+Read more about the instructions to sync a fork from the WebUI, from the GitHub CI, or from the command line at [Syncing a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
+
+## SSH to CI jobs
+
+The additional benefit of the "Personal CI" is that you get SSH access to the build VMs when the build is running. That is handled by this logic in the [pulsar-ci.yaml](https://github.com/apache/pulsar/blob/master/.github/workflows/pulsar-ci.yaml) GitHub Actions workflow file:
+
+```yaml
+- name: Setup ssh access to build runner VM
+ # ssh access is enabled for builds in own forks
+ if: ${{ github.repository != 'apache/pulsar' && github.event_name == 'pull_request' }}
+ uses: ./.github/actions/ssh-access
+ with:
+ limit-access-to-actor: true
+```
+
+Here is [the inline `ssh-access` composite action implementation](https://github.com/apache/pulsar/blob/master/.github/actions/ssh-access/action.yml).
+
+The SSH access is secured with the SSH key registered in GitHub. For example, your public keys are https://github.com/horizonzy.keys. You will first have to register an SSH public key in GitHub for that to work.
diff --git a/site2/website-next/contribute/releasing/release-note-guide.md b/site2/website-next/contribute/release-note-guide.md
similarity index 65%
rename from site2/website-next/contribute/releasing/release-note-guide.md
rename to site2/website-next/contribute/release-note-guide.md
index 4d8ee4b7f11..27575d450e9 100644
--- a/site2/website-next/contribute/releasing/release-note-guide.md
+++ b/site2/website-next/contribute/release-note-guide.md
@@ -1,7 +1,6 @@
---
id: release-note-guide
title: Release Note Guide
-sidebar_label: "Release Note Guide"
---
This guide explains everything about Pulsar release notes.
@@ -15,8 +14,8 @@ This chapter gives an overview of Pulsar release notes.
[Pulsar release notes](/release-notes/) consist of the following parts.
| Release note | Component |
-| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| [Pulsar Core](/release-notes/#pulsar-release-notes) | <div align="center">Pulsar</div> |
+|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------|
+| [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
@@ -42,7 +41,7 @@ gh release view "v2.10.2" -R apache/pulsar --json body --jq .body
The process is similar to update standalone client releases.
-To preview the result, follow the instructions documented at the [Content Preview Guide](/contribute/documentation/preview.md#preview-website-changes).
+To preview the result, follow the instructions documented at the [Content Preview Guide](document-preview.md#preview-website-changes).
## Submit release notes
@@ -50,23 +49,23 @@ Follow the steps below to submit release notes for Pulsar and clients (**Java an
:::note
-For **C++, Python, Go, Node.js, and C#**, you do not need to take care of them since their release notes are synced from their repos to the [Pulsar Release Note page](https://pulsar.apache.org/release-notes).
+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/).
:::
-1. Submit a PR to add **separate** release notes for Pulsar and clients (**Java and WebSocket**) to [pulsar-site/site2/website-next/release-notes/versioned/](https://github.com/apache/pulsar-site/tree/main/site2/website-next/release-notes/versioned).
+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 - GitHub](https://github.com/apache/pulsar/releases).
+3. Copy the release note to the [Pulsar Releases Page on GitHub](https://github.com/apache/pulsar/releases).
| 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:
+
+ 
- 
-
- After the new release is published, all the information about the release is automatically added to the [Pulsar Release Note page](https://pulsar.apache.org/release-notes/).
+ After the new release is published, all the information about the release is automatically added to the [Pulsar Release Note page](/release-notes/).
-4. Check whether the release information is shown on the [Pulsar Release Note page](https://pulsar.apache.org/release-notes/) after the website is updated and built successfully.
+4. Check whether the release information is shown on the [Pulsar Release Note page](/release-notes/) after the website is updated and built successfully.
diff --git a/site2/website-next/contribute/releasing/release-process.md b/site2/website-next/contribute/release-process.md
similarity index 99%
rename from site2/website-next/contribute/releasing/release-process.md
rename to site2/website-next/contribute/release-process.md
index 33c8e19ed8c..6de8ec445dc 100644
--- a/site2/website-next/contribute/releasing/release-process.md
+++ b/site2/website-next/contribute/release-process.md
@@ -1,7 +1,6 @@
---
id: release-process
title: Release Process
-sidebar_label: "Release Process"
---
This page contains instructions for Pulsar committers on how to perform a release.
diff --git a/site2/website-next/contribute/releasing/_category_.json b/site2/website-next/contribute/releasing/_category_.json
deleted file mode 100644
index 6def1d9c705..00000000000
--- a/site2/website-next/contribute/releasing/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
- "label": "Releasing",
- "position": 5,
- "link": {
- "type": "generated-index"
- }
-}
diff --git a/site2/website-next/contribute/getting-started/setup-building.md b/site2/website-next/contribute/setup-building.md
similarity index 81%
rename from site2/website-next/contribute/getting-started/setup-building.md
rename to site2/website-next/contribute/setup-building.md
index 66600b49155..30b948b623d 100644
--- a/site2/website-next/contribute/getting-started/setup-building.md
+++ b/site2/website-next/contribute/setup-building.md
@@ -1,13 +1,12 @@
---
id: setup-building
title: Setup and Building
-sidebar_label: "Setup and Building"
---
## Prerequisites
| Dependency | Description |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Git | The source code of Pulsar is hosted on GitHub as a git repository. To work with the git repository, please [install git](https://git-scm.com/downloads). |
| JDK | The source code of Pulsar is almost written in Java. Therefore, you need a working Java Development Kit (JDK) to build it. Pulsar requires [JDK 17](https://adoptium.net/temurin/releases/?version=17) to build. |
| Maven | The source code of Pulsar is managed by [Apache Maven](https://maven.apache.org/) The required Maven version is 3.6.1+. |
@@ -27,34 +26,27 @@ Clone the source code to your development machine:
git clone https://github.com/apache/pulsar
```
-## Build
-
-Compile and install:
+The following commands are assumed to be executed from the project root directory:
```bash
-mvn clean install -DskipTests
+cd pulsar
```
-## Run unit tests
-
-```bash
-mvn test
-```
+## Build
-Run individual unit test:
+Compile and install to local Maven repository:
```bash
-# mvn -pl <module-name> test -Dtest=<unit-test-name> # for example:
-mvn -pl pulsar-client test -Dtest=ConsumerBuilderImplTest
+mvn clean install -DskipTests
```
-## Start standalone Pulsar service
+## Run
```bash
bin/pulsar standalone
```
-## Connect to the standalone service:
+## Connect
```bash
bin/pulsar-shell
diff --git a/site2/website-next/contribute/getting-started/setup-ide.md b/site2/website-next/contribute/setup-ide.md
similarity index 57%
rename from site2/website-next/contribute/getting-started/setup-ide.md
rename to site2/website-next/contribute/setup-ide.md
index 37cf82734c3..f92c8e9d858 100644
--- a/site2/website-next/contribute/getting-started/setup-ide.md
+++ b/site2/website-next/contribute/setup-ide.md
@@ -1,50 +1,47 @@
---
id: setup-ide
-title: Setup IDE
-sidebar_label: "Setup IDE"
+title: Setting up an IDE
---
-Apache Pulsar is using [lombok](https://projectlombok.org/) so you have to ensure your IDE setup with required plugins.
+Apache Pulsar is using [lombok](https://projectlombok.org/), so you have to ensure your IDE setup with required plugins.
## IntelliJ IDEA
-### Configure Project JDK to Java 17 JDK
+### Configure Project JDK to JDK 17
-1. Open **Project Settings**.
+1. Open **Project Settings**. Click **File** → **Project Structure** → **Project Settings** → **Project**.
+2. Select the JDK version. From the JDK version drop-down list, select **Download JDK...** or choose an existing recent Java 17 JDK version.
+3. In the download dialog, select version **17** and vendor **Eclipse Temurin (AdoptOpenJDK HotSpot)**.
- Click **File** -> **Project Structure** -> **Project Settings** -> **Project**.
+### Configure Java version for Maven
-2. Select the JDK version.
+1. Open Maven Importing Settings. Click **Settings** → **Build, Execution, Deployment** → **Build Tools** → **Maven** → **Importing**.
+2. For **JDK for Importer** setting, select **Use Project JDK**. This uses the Java 17 JDK for running Maven when importing the project.
+3. Ensure that the JRE setting in **Maven** → **Runner** dialog is set to **Use Project JDK**.
- From the JDK version drop-down list, select **Download JDK...** or choose an existing recent Java 17 JDK version.
+:::caution
-3. In the download dialog, select version **17**. You can pick a version from many vendors. Unless you have a specific preference, choose **Eclipse Temurin (AdoptOpenJDK (Hotspot))**.
+Some configuration in the Maven build is conditional based on the JDK version. Incorrect configuration gets chosen when the "JDK for Importer" isn't the same as the "Project JDK".
-### Configure Java version for Maven in IntelliJ
-
-1. Open Maven Importing Settings dialog by going to **Settings** -> **Build, Execution, Deployment** -> **Build Tools** -> **Maven** -> **Importing**.
-
-2. Choose **Use Project JDK** for **JDK for Importer** setting. This uses the Java 17 JDK for running Maven when importing the project to IntelliJ. Some of the configuration in the Maven build is conditional based on the JDK version. Incorrect configuration gets chosen when the "JDK for Importer" isn't the same as the "Project JDK".
-
-3. Validate that the JRE setting in **Maven** -> **Runner** dialog is set to **Use Project JDK**.
+:::
-### Configure annotation processing in IntelliJ
+### Configure annotation processing
-1. Open Annotation Processors Settings dialog box by going to **Settings** -> **Build, Execution, Deployment** -> **Compiler** -> **Annotation Processors**.
+1. Open Annotation Processors Settings. Click **Settings** → **Build, Execution, Deployment** → **Compiler** → **Annotation Processors**.
2. Select the following buttons:
1. **Enable annotation processing**
2. **Obtain processors from project classpath**
- 3. Store generated sources relative to: **Module content root**
+ 3. Store generated sources relative to: **Module output directory**
3. Set the generated source directories to be equal to the Maven directories:
- 1. Set "Production sources directory:" to "target/generated-sources/annotations".
- 2. Set "Test sources directory:" to "target/generated-test-sources/test-annotations".
+ 1. Set "Production sources directory:" to "generated-sources".
+ 2. Set "Test sources directory:" to "generated-test-sources".
4. Click **OK**.
5. Install the lombok plugin in intelliJ.
### Configure code style
-1. Open Code Style Settings dialog box by going to **Settings** -> **Editor** -> **Code Style**.
-2. Click on the :gear: symbol -> **Import scheme** -> **IntelliJ IDEA code style XML**
+1. Open Code Style Settings dialog box by going to **Settings** → **Editor** → **Code Style**.
+2. Click on the :gear: symbol → **Import scheme** → **IntelliJ IDEA code style XML**
3. Pick the file `${pulsar_dir}/src/idea-code-style.xml`
4. On the dialog box that opens, click **OK**.
5. Ensure the scheme you just created is selected in **Scheme** dropdown then click **OK**.
@@ -52,19 +49,19 @@ Apache Pulsar is using [lombok](https://projectlombok.org/) so you have to ensur
### Configure Checkstyle
1. Install the Checkstyle-IDEA plugin.
-2. Open Checkstyle Settings dialog box by going to **Settings** -> **Tools** -> **Checkstyle**.
+2. Open Checkstyle Settings. Click **Settings** → **Tools** → **Checkstyle**.
3. Set **Checkstyle version** to **8.37**.
4. Set **Scan scope** to **Only Java sources (including tests)**.
-5. Click **+** button in the **Configuration** section to open a dialog to choose the checkfile file.
+5. Click **+** button in the **Configuration** section to open a dialog to choose the checkstyle config file.
1. Enter a **Description**. For example, Pulsar.
2. Select **Use a local checkstyle file**.
3. Set **File** to **buildtools/src/main/resources/pulsar/checkstyle.xml**.
4. Select **Store relative to project location**.
- 5. Click **Next** -> **Next** -> **Finish**.
+ 5. Click **Next** → **Next** → **Finish**.
6. Activate the configuration you just added by toggling the corresponding box.
7. Click **OK**.
-### Further configuration in IntelliJ
+### Further configuration
* When working on the Pulsar core modules in IntelliJ, reduce the number of active projects in IntelliJ to speed up IDE actions and reduce unrelated IDE warnings.
* In IntelliJ's Maven UI's tree view under "Profiles"
@@ -73,10 +70,10 @@ Apache Pulsar is using [lombok](https://projectlombok.org/) so you have to ensur
* Run the "Reload All Maven Projects" action from the Maven UI toolbar. You can also find the action by the name in the IntelliJ "Search Everywhere" window that gets activated by pressing the **Shift** key twice.
* Run the "Generate Sources and Update Folders For All Projects" action from the Maven UI toolbar. You can also find the action by the name in the IntelliJ "Search Everywhere" window that gets activated by pressing the **Shift** key twice. Running the action takes about 10 minutes for all projects. This is faster when the "core-modules" profile is the only active profile.
-:::tip
+### Troubleshooting
* In the case of compilation errors with missing Protobuf classes, ensure to run the "Generate Sources and Update Folders For All Projects" action.
-* All of the Pulsar source code doesn't compile properly in IntelliJ and there are compilation errors.
+* When all the Pulsar source code doesn't compile properly in IntelliJ and there are compilation errors:
* Use the "core-modules" profile if working on the Pulsar core modules since the source code for those modules can be compiled in IntelliJ.
* Sometimes it might help to mark a specific project ignored in IntelliJ Maven UI by right-clicking the project name and select **Ignore Projects** from the menu.
* Currently, it is not always possible to run unit tests directly from the IDE because of the compilation issues. As a workaround, individual test classes can be run by using the `mvn test -Dtest=TestClassName` command.
@@ -86,11 +83,9 @@ Apache Pulsar is using [lombok](https://projectlombok.org/) so you have to ensur
2. Run `mvn clean install -DskipTests` on the command line.
3. Reopen IntelliJ.
* If that still doesn't work:
- 1. Verify Maven is using a supported version. Currently, the supported version of Maven is specified in the `<requireMavenVersion>` section of the main pom.xml file.
+ 1. Verify Maven is using a supported version. Currently, the supported version of Maven is specified in the `<requireMavenVersion>` section of the root `pom.xml` file.
2. Try "restart and clear caches" in IntelliJ and repeat the above steps to reload projects and generate sources.
-:::
-
## Eclipse
-Follow the instructions [here](https://howtodoinjava.com/automation/lombok-eclipse-installation-examples/) to configure your Eclipse setup.
+Follow [these instructions](https://howtodoinjava.com/automation/lombok-eclipse-installation-examples/) to configure your Eclipse setup.
diff --git a/site2/website-next/contribute/testing-and-ci/_category_.json b/site2/website-next/contribute/testing-and-ci/_category_.json
deleted file mode 100644
index c1473a070f8..00000000000
--- a/site2/website-next/contribute/testing-and-ci/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
- "label": "Testing and CI",
- "position": 10,
- "link": {
- "type": "generated-index"
- }
-}
diff --git a/site2/website-next/contribute/testing-and-ci/ci-testing-in-fork.md b/site2/website-next/contribute/testing-and-ci/ci-testing-in-fork.md
deleted file mode 100644
index 243b9d6cd59..00000000000
--- a/site2/website-next/contribute/testing-and-ci/ci-testing-in-fork.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-id: ci-testing-in-fork
-title: CI Testing in Fork
-sidebar_label: "CI Testing in Fork"
----
-
-Pulsar CI is currently hosted on Apache Infra resources. Since we cannot add more resources to Pulsar CI, we need to find other ways to reduce the load on Pulsar CI.
-
-After [PR-17693](https://github.com/apache/pulsar/pull/17693) merged, any pull request directly sent to `apache/pulsar` won't be triggered any more.
-
-That said, pull requests should be first tested in your own fork. GitHub Actions provides separate quota for pull requests that are executed in a forked repository.
-
-## Run CI in fork
-
-Here are instructions to use your personal CI on GitHub:
-
-1. Push your intended pull request changes to a new branch in your fork (the usual way you do it).
-2. Open a pull request to your own fork.
-
-These are the instructions for command-line interface:
-
-Install [GitHub CLI](https://cli.github.com/) and configure it. With GitHub CLI, there's an easy way to open the PR to your own fork with a single command:
-
-```bash
-gh pr create --repo=<your-github-id>/pulsar --base master --head <your-pr-branch> -f
-```
-
-Alternatively, you can also create a PR to your own fork in the GitHub UI when opening a new PR. To do so, first click on "compare across forks" and then choose your own fork as both the forked repository and head repository.
-
-## Stay in-sync with upstream
-
-It's worth keeping your master branch in sync with apache/pulsar's master so that the PR diff will be reasonable in your own fork.
-
-Here's one way to sync your fork's master branch with apache/pulsar's master branch: Let's say you have git remotes called "upstream" for apache/pulsar and "forked" for your fork, with these commands, you synchronize your fork's remote master branch with apache/pulsar's master branch:
-
-* replace "upstream" with the name of the git remote for apache/pulsar
-* replace "forked" with the name of the git remote for your fork of pulsar
-
-```bash
-git fetch upstream
-git push -f forked upstream/master:master
-```
-
-When you finally want to create a PR to apache/pulsar, it can be started from the command line (this will open a browser for filling in the PR details):
-
-```bash
-gh pr create --repo=apache/pulsar --base master --head <your-pr-branch> --web
-```
-
-## SSH to CI jobs
-
-The additional benefit of the "Personal CI" is that you get SSH access to the build VMs when the build is running. That is handled by this logic in the [pulsar-ci.yaml](https://github.com/apache/pulsar/blob/master/.github/workflows/pulsar-ci.yaml) GitHub Actions workflow file:
-
-```yaml
-- name: Setup ssh access to build runner VM
- # ssh access is enabled for builds in own forks
- if: ${{ github.repository != 'apache/pulsar' && needs.changed_files_job.outputs.docs_only != 'true' }}
- uses: ./.github/actions/ssh-access
- with:
- limit-access-to-actor: true
-```
-
-... and [the inline composite action implementation](https://github.com/apache/pulsar/blob/master/.github/actions/ssh-access/action.yml). The SSH access is secured with the SSH key registered in GitHub. For example, your public keys are https://github.com/horizonzy.keys. You will first have to register an SSH public key in GitHub for that to work.
diff --git a/site2/website-next/contribute/testing-and-ci/licensing.md b/site2/website-next/contribute/testing-licenses.md
similarity index 84%
rename from site2/website-next/contribute/testing-and-ci/licensing.md
rename to site2/website-next/contribute/testing-licenses.md
index 6c30cddd37a..eef298be99a 100644
--- a/site2/website-next/contribute/testing-and-ci/licensing.md
+++ b/site2/website-next/contribute/testing-licenses.md
@@ -1,7 +1,6 @@
---
-id: licensing
-title: Licensing
-sidebar_label: "Licensing"
+id: testing-licenses
+title: License Format
---
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/site2/website-next/contribute/releasing/validate-release-candidate.md b/site2/website-next/contribute/validate-release-candidate.md
similarity index 99%
rename from site2/website-next/contribute/releasing/validate-release-candidate.md
rename to site2/website-next/contribute/validate-release-candidate.md
index 962f5e6624d..ea2c042966a 100644
--- a/site2/website-next/contribute/releasing/validate-release-candidate.md
+++ b/site2/website-next/contribute/validate-release-candidate.md
@@ -1,7 +1,6 @@
---
id: validate-release-candidate
title: Validate Release Candidate
-sidebar_label: "Validate Release Candidate"
---
The following are manual instructions for reviewing and validating a release candidate.
@@ -617,7 +616,7 @@ Checkout the result in the terminal of step 3.
Produce another 10 messages "hello". The result is updated to 20.
-```json
+```bash
bin/pulsar-client produce -m "hello" -n 10 test_wordcount_src
```
diff --git a/site2/website-next/docusaurus.config.js b/site2/website-next/docusaurus.config.js
index 791eadc1d36..1d46132f5d2 100644
--- a/site2/website-next/docusaurus.config.js
+++ b/site2/website-next/docusaurus.config.js
@@ -422,7 +422,7 @@ module.exports = {
routeBasePath: 'contribute',
showLastUpdateAuthor: true,
showLastUpdateTime: true,
- sidebarPath: require.resolve('./sidebarsContribute.js'),
+ sidebarPath: require.resolve('./sidebarsDevelopment.js'),
editUrl: 'https://github.com/apache/pulsar-site/tree/main/site2/website-next',
},
],
diff --git a/site2/website-next/sidebarsContribute.js b/site2/website-next/sidebarsContribute.js
deleted file mode 100644
index 4f4bda0ac35..00000000000
--- a/site2/website-next/sidebarsContribute.js
+++ /dev/null
@@ -1,6 +0,0 @@
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
- sidebar: [{type: 'autogenerated', dirName: '.'}],
-};
-
-module.exports = sidebars;
diff --git a/site2/website-next/sidebarsDevelopment.js b/site2/website-next/sidebarsDevelopment.js
new file mode 100644
index 00000000000..a06d04913d2
--- /dev/null
+++ b/site2/website-next/sidebarsDevelopment.js
@@ -0,0 +1,77 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+ sidebarDevelopment: [
+ 'about',
+ {
+ "type": "category",
+ "label": "Getting Started",
+ link: {
+ type: 'generated-index',
+ },
+ items: [
+ 'setup-building',
+ 'setup-ide',
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Development",
+ link: {
+ type: 'generated-index',
+ },
+ items: [
+ 'develop-labels',
+ 'develop-semantic-title'
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Testing and CI",
+ link: {
+ type: 'generated-index',
+ },
+ items: [
+ 'testing-licenses',
+ 'personal-ci',
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Documentation",
+ link: {
+ type: 'generated-index',
+ },
+ items: [
+ 'document-intro',
+ 'document-contribution',
+ 'document-syntax',
+ 'document-preview',
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Releases",
+ link: {
+ type: 'generated-index',
+ },
+ items: [
+ 'create-gpg-keys',
+ 'validate-release-candidate',
+ 'release-process',
+ 'release-note-guide',
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Committers",
+ link: {
+ type: 'generated-index',
+ },
+ items: [
+ 'become-core-developer',
+ ]
+ }
+ ],
+};
+
+module.exports = sidebars;
diff --git a/site2/website-next/static/reference/next/config/reference-configuration-bookkeeper.md b/site2/website-next/static/reference/next/config/reference-configuration-bookkeeper.md
new file mode 100644
index 00000000000..28e85dcaf6c
--- /dev/null
+++ b/site2/website-next/static/reference/next/config/reference-configuration-bookkeeper.md
@@ -0,0 +1,583 @@
+# BookKeeper
+
+BookKeeper is a replicated log storage system that Pulsar uses for durable storage of all messages.
+
+### bookiePort
+
+The port on which the bookie server listens.
+
+**Default**: 3181
+
+### allowLoopback
+
+Whether the bookie is allowed to use a loopback interface as its primary interface (that is the interface used to establish its identity). By default, loopback interfaces are not allowed to work as the primary interface. Using a loopback interface as the primary interface usually indicates a configuration error. For example, it’s fairly common in some VPS setups to not configure a hostname or to have the hostname resolve to `127.0.0.1`. If this is the case, then all bookies in the cluste [...]
+
+**Default**: false
+
+### listeningInterface
+
+The network interface on which the bookie listens. By default, the bookie listens on all interfaces.
+
+**Default**: eth0
+
+### advertisedAddress
+
+Configure a specific hostname or IP address that the bookie should use to advertise itself to clients. By default, the bookie advertises either its own IP address or hostname according to the `listeningInterface` and `useHostNameAsBookieID` settings.
+
+**Default**: N/A
+
+### allowMultipleDirsUnderSameDiskPartition
+
+Configure the bookie to enable/disable multiple ledger/index/journal directories in the same filesystem disk partition.
+
+**Default**: false
+
+### minUsableSizeForIndexFileCreation
+
+The minimum safe usable size available in index directory for bookie to create index files while replaying journal at the time of bookie starts in Readonly Mode (in bytes).
+
+**Default**: 1073741824
+
+### journalDirectory
+
+The directory where BookKeeper outputs its write-ahead log (WAL).
+
+**Default**: data/bookkeeper/journal
+
+### journalDirectories
+
+Directories that BookKeeper outputs its write ahead log. Multiple directories are available, being separated by `,`. For example: `journalDirectories=/tmp/bk-journal1,/tmp/bk-journal2`. If `journalDirectories` is set, the bookies skip `journalDirectory` and use this setting directory.
+
+**Default**: /tmp/bk-journal
+
+### ledgerDirectories
+
+The directory where BookKeeper outputs ledger snapshots. This could define multiple directories to store snapshots separated by `,`, for example `ledgerDirectories=/tmp/bk1-data,/tmp/bk2-data`. Ideally, ledger dirs and the journal dir are each in a different device, which reduces the contention between random I/O and sequential write. It is possible to run with a single disk, but performance will be significantly lower.
+
+**Default**: data/bookkeeper/ledgers
+
+### ledgerManagerType
+
+The type of ledger manager used to manage how ledgers are stored, managed, and garbage collected. See [BookKeeper Internals](https://bookkeeper.apache.org/docs/next/getting-started/concepts) for more info.
+
+**Default**: hierarchical
+
+### zkLedgersRootPath
+
+The root ZooKeeper path used to store ledger metadata. This parameter is used by the ZooKeeper-based ledger manager as a root znode to store all ledgers.
+
+**Default**: /ledgers
+
+### ledgerStorageClass
+
+Ledger storage implementation class
+
+**Default**: org.apache.bookkeeper.bookie.storage.ldb.DbLedgerStorage
+
+### entryLogFilePreallocationEnabled
+
+Enable or disable entry logger preallocation
+
+**Default**: true
+
+### logSizeLimit
+
+Max file size of the entry logger, in bytes. A new entry log file will be created when the old one reaches the file size limitation.
+
+**Default**: 1073741824
+
+### minorCompactionThreshold
+
+Threshold of minor compaction. Entry log files whose remaining size percentage reaches below this threshold will be compacted in a minor compaction. If set to less than zero, the minor compaction is disabled.
+
+**Default**: 0.2
+
+### minorCompactionInterval
+
+Time interval to run minor compaction, in seconds. If set to less than zero, the minor compaction is disabled. Note: should be greater than gcWaitTime.
+
+**Default**: 3600
+
+### majorCompactionThreshold
+
+The threshold of major compaction. Entry log files whose remaining size percentage reaches below this threshold will be compacted in a major compaction. Those entry log files whose remaining size percentage is still higher than the threshold will never be compacted. If set to less than zero, the major compaction is disabled.
+
+**Default**: 0.5
+
+### majorCompactionInterval
+
+The time interval to run major compaction, in seconds. If set to less than zero, the major compaction is disabled. Note: should be greater than gcWaitTime.
+
+**Default**: 86400
+
+### readOnlyModeEnabled
+
+If `readOnlyModeEnabled=true`, then on all full ledger disks, bookie will be converted to read-only mode and serve only read requests. Otherwise the bookie will be shutdown.
+
+**Default**: true
+
+### forceReadOnlyBookie
+
+Whether the bookie is force started in read only mode.
+
+**Default**: false
+
+### persistBookieStatusEnabled
+
+Persist the bookie status locally on the disks. So the bookies can keep their status upon restarts.
+
+**Default**: false
+
+### compactionMaxOutstandingRequests
+
+Sets the maximum number of entries that can be compacted without flushing. When compacting, the entries are written to the entrylog and the new offsets are cached in memory. Once the entrylog is flushed the index is updated with the new offsets. This parameter controls the number of entries added to the entrylog before a flush is forced. A higher value for this parameter means more memory will be used for offsets. Each offset consists of 3 longs. This parameter should not be modified unl [...]
+
+**Default**: 100000
+
+### compactionRate
+
+The rate at which compaction will read entries, in adds per second.
+
+**Default**: 1000
+
+### isThrottleByBytes
+
+Throttle compaction by bytes or by entries.
+
+**Default**: false
+
+### compactionRateByEntries
+
+The rate at which compaction will read entries, in adds per second.
+
+**Default**: 1000
+
+### compactionRateByBytes
+
+Set the rate at which compaction reads entries. The unit is bytes added per second.
+
+**Default**: 1000000
+
+### journalMaxSizeMB
+
+Max file size of journal file, in megabytes. A new journal file will be created when the old one reaches the file size limitation.
+
+**Default**: 2048
+
+### journalMaxBackups
+
+The max number of old journal files to keep. Keeping a number of old journal files would help data recovery in special cases.
+
+**Default**: 5
+
+### journalPreAllocSizeMB
+
+How space to pre-allocate at a time in the journal.
+
+**Default**: 16
+
+### journalWriteBufferSizeKB
+
+The of the write buffers used for the journal.
+
+**Default**: 64
+
+### journalRemoveFromPageCache
+
+Whether pages should be removed from the page cache after force write.
+
+**Default**: true
+
+### journalAdaptiveGroupWrites
+
+Whether to group journal force writes, which optimizes group commit for higher throughput.
+
+**Default**: true
+
+### journalMaxGroupWaitMSec
+
+The maximum latency to impose on a journal write to achieve grouping.
+
+**Default**: 1
+
+### journalAlignmentSize
+
+All the journal writes and commits should be aligned to given size
+
+**Default**: 4096
+
+### journalBufferedWritesThreshold
+
+Maximum writes to buffer to achieve grouping
+
+**Default**: 524288
+
+### journalFlushWhenQueueEmpty
+
+If we should flush the journal when journal queue is empty
+
+**Default**: false
+
+### numJournalCallbackThreads
+
+The number of threads that should handle journal callbacks
+
+**Default**: 8
+
+### openLedgerRereplicationGracePeriod
+
+The grace period, in milliseconds, that the replication worker waits before fencing and replicating a ledger fragment that's still being written to upon bookie failure.
+
+**Default**: 30000
+
+### rereplicationEntryBatchSize
+
+The number of max entries to keep in fragment for re-replication
+
+**Default**: 100
+
+### autoRecoveryDaemonEnabled
+
+Whether the bookie itself can start auto-recovery service.
+
+**Default**: true
+
+### lostBookieRecoveryDelay
+
+How long to wait, in seconds, before starting auto recovery of a lost bookie.
+
+**Default**: 0
+
+### gcWaitTime
+
+How long the interval to trigger next garbage collection, in milliseconds. Since garbage collection is running in background, too frequent gc will heart performance. It is better to give a higher number of gc interval if there is enough disk capacity.
+
+**Default**: 900000
+
+### gcOverreplicatedLedgerWaitTime
+
+How long the interval to trigger next garbage collection of overreplicated ledgers, in milliseconds. This should not be run very frequently since we read the metadata for all the ledgers on the bookie from zk.
+
+**Default**: 86400000
+
+### flushInterval
+
+How long the interval to flush ledger index pages to disk, in milliseconds. Flushing index files will introduce much random disk I/O. If separating journal dir and ledger dirs each on different devices, flushing would not affect performance. But if putting journal dir and ledger dirs on same device, performance degrade significantly on too frequent flushing. You can consider increment flush interval to get better performance, but you need to pay more time on bookie server restart after failure.
+
+**Default**: 60000
+
+### bookieDeathWatchInterval
+
+Interval to watch whether bookie is dead or not, in milliseconds
+
+**Default**: 1000
+
+### allowStorageExpansion
+
+Allow the bookie storage to expand. Newly added ledger and index dirs must be empty.
+
+**Default**: false
+
+### zkServers
+
+A list of one of more servers on which zookeeper is running. The server list can be comma separated values, for example: zkServers=zk1:2181,zk2:2181,zk3:2181.
+
+**Default**: localhost:2181
+
+### zkTimeout
+
+ZooKeeper client session timeout in milliseconds Bookie server will exit if it received SESSION_EXPIRED because it was partitioned off from ZooKeeper for more than the session timeout JVM garbage collection, disk I/O will cause SESSION_EXPIRED. Increment this value could help avoiding this issue
+
+**Default**: 30000
+
+### zkRetryBackoffStartMs
+
+The start time that the Zookeeper client backoff retries in milliseconds.
+
+**Default**: 1000
+
+### zkRetryBackoffMaxMs
+
+The maximum time that the Zookeeper client backoff retries in milliseconds.
+
+**Default**: 10000
+
+### zkEnableSecurity
+
+Set ACLs on every node written on ZooKeeper, allowing users to read and write BookKeeper metadata stored on ZooKeeper. In order to make ACLs work you need to setup ZooKeeper JAAS authentication. All the bookies and Client need to share the same user, and this is usually done using Kerberos authentication. See ZooKeeper documentation.
+
+**Default**: false
+
+### httpServerEnabled
+
+The flag enables/disables starting the admin http server.
+
+**Default**: false
+
+### httpServerPort
+
+The HTTP server port to listen on. By default, the value is `8080`. If you want to keep it consistent with the Prometheus stats provider, you can set it to `8000`.
+
+**Default**: 8080
+
+### httpServerClass
+
+The http server class.
+
+**Default**: org.apache.bookkeeper.http.vertx.VertxHttpServer
+
+### serverTcpNoDelay
+
+This settings is used to enabled/disabled Nagle’s algorithm, which is a means of improving the efficiency of TCP/IP networks by reducing the number of packets that need to be sent over the network. If you are sending many small messages, such that more than one can fit in a single IP packet, setting server.tcpnodelay to false to enable Nagle algorithm can provide better performance.
+
+**Default**: true
+
+### serverSockKeepalive
+
+This setting is used to send keep-alive messages on connection-oriented sockets.
+
+**Default**: true
+
+### serverTcpLinger
+
+The socket linger timeout on close. When enabled, a close or shutdown will not return until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Otherwise, the call returns immediately and the closing is done in the background.
+
+**Default**: 0
+
+### byteBufAllocatorSizeMax
+
+The maximum buf size of the received ByteBuf allocator.
+
+**Default**: 1048576
+
+### nettyMaxFrameSizeBytes
+
+The maximum netty frame size in bytes. Any message received larger than this will be rejected.
+
+**Default**: 5253120
+
+### openFileLimit
+
+Max number of ledger index files could be opened in bookie server If number of ledger index files reaches this limitation, bookie server started to swap some ledgers from memory to disk. Too frequent swap will affect performance. You can tune this number to gain performance according your requirements.
+
+**Default**: 0
+
+### pageSize
+
+Size of a index page in ledger cache, in bytes A larger index page can improve performance writing page to disk, which is efficient when you have small number of ledgers and these ledgers have similar number of entries. If you have large number of ledgers and each ledger has fewer entries, smaller index page would improve memory usage.
+
+**Default**: 8192
+
+### pageLimit
+
+How many index pages provided in ledger cache If number of index pages reaches this limitation, bookie server starts to swap some ledgers from memory to disk. You can increment this value when you found swap became more frequent. But make sure pageLimit\*pageSize should not more than JVM max memory limitation, otherwise you would got OutOfMemoryException. In general, incrementing pageLimit, using smaller index page would gain better performance in lager number of ledgers with fewer entri [...]
+
+**Default**: 0
+
+### readOnlyModeEnabled
+
+If all ledger directories configured are full, then support only read requests for clients. If "readOnlyModeEnabled=true" then on all ledger disks full, bookie will be converted to read-only mode and serve only read requests. Otherwise the bookie will be shutdown. By default this will be disabled.
+
+**Default**: true
+
+### diskUsageThreshold
+
+For each ledger dir, maximum disk space which can be used. Default is 0.95f. i.e. 95% of disk can be used at most after which nothing will be written to that partition. If all ledger dir partitions are full, then bookie will turn to readonly mode if ‘readOnlyModeEnabled=true’ is set, else it will shutdown. Valid values should be in between 0 and 1 (exclusive).
+
+**Default**: 0.95
+
+### diskCheckInterval
+
+Disk check interval in milli seconds, interval to check the ledger dirs usage.
+
+**Default**: 10000
+
+### auditorPeriodicCheckInterval
+
+Interval at which the auditor will do a check of all ledgers in the cluster. By default this runs once a week. The interval is set in seconds. To disable the periodic check completely, set this to 0. Note that periodic checking will put extra load on the cluster, so it should not be run more frequently than once a day.
+
+**Default**: 604800
+
+### sortedLedgerStorageEnabled
+
+Whether sorted-ledger storage is enabled.
+
+**Default**: true
+
+### auditorPeriodicBookieCheckInterval
+
+The interval between auditor bookie checks. The auditor bookie check, checks ledger metadata to see which bookies should contain entries for each ledger. If a bookie which should contain entries is unavailable, thea the ledger containing that entry is marked for recovery. Setting this to 0 disabled the periodic check. Bookie checks will still run when a bookie fails. The interval is specified in seconds.
+
+**Default**: 86400
+
+### numAddWorkerThreads
+
+The number of threads that should handle write requests. if zero, the writes would be handled by netty threads directly.
+
+**Default**: 0
+
+### numReadWorkerThreads
+
+The number of threads that should handle read requests. if zero, the reads would be handled by netty threads directly.
+
+**Default**: 8
+
+### numHighPriorityWorkerThreads
+
+The umber of threads that should be used for high priority requests (i.e. recovery reads and adds, and fencing).
+
+**Default**: 8
+
+### maxPendingReadRequestsPerThread
+
+If read workers threads are enabled, limit the number of pending requests, to avoid the executor queue to grow indefinitely.
+
+**Default**: 2500
+
+### maxPendingAddRequestsPerThread
+
+The limited number of pending requests, which is used to avoid the executor queue to grow indefinitely when add workers threads are enabled.
+
+**Default**: 10000
+
+### isForceGCAllowWhenNoSpace
+
+Whether force compaction is allowed when the disk is full or almost full. Forcing GC could get some space back, but could also fill up the disk space more quickly. This is because new log files are created before GC, while old garbage log files are deleted after GC.
+
+**Default**: false
+
+### verifyMetadataOnGC
+
+True if the bookie should double check `readMetadata` prior to GC.
+
+**Default**: false
+
+### flushEntrylogBytes
+
+Entry log flush interval in bytes. Flushing in smaller chunks but more frequently reduces spikes in disk I/O. Flushing too frequently may also affect performance negatively.
+
+**Default**: 268435456
+
+### readBufferSizeBytes
+
+The number of bytes we should use as capacity for BufferedReadChannel.
+
+**Default**: 4096
+
+### writeBufferSizeBytes
+
+The number of bytes used as capacity for the write buffer
+
+**Default**: 65536
+
+### useHostNameAsBookieID
+
+Whether the bookie should use its hostname to register with the coordination service (e.g.: zookeeper service). When false, bookie will use its ip address for the registration.
+
+**Default**: false
+
+### bookieId
+
+If you want to custom a bookie ID or use a dynamic network address for the bookie, you can set the `bookieId`. <br /><br />Bookie advertises itself using the `bookieId` rather than the `BookieSocketAddress` (`hostname:port` or `IP:port`). If you set the `bookieId`, then the `useHostNameAsBookieID` does not take effect.<br /><br />The `bookieId` is a non-empty string that can contain ASCII digits and letters ([a-zA-Z9-0]), colons, dashes, and dots. <br /><br />For more information about ` [...]
+
+**Default**: N/A
+
+### allowEphemeralPorts
+
+Whether the bookie is allowed to use an ephemeral port (port 0) as its server port. By default, an ephemeral port is not allowed. Using an ephemeral port as the service port usually indicates a configuration error. However, in unit tests, using an ephemeral port will address port conflict problems and allow running tests in parallel.
+
+**Default**: false
+
+### enableLocalTransport
+
+Whether the bookie is allowed to listen for the BookKeeper clients executed on the local JVM.
+
+**Default**: false
+
+### disableServerSocketBind
+
+Whether the bookie is allowed to disable bind on network interfaces. This bookie will be available only to BookKeeper clients executed on the local JVM.
+
+**Default**: false
+
+### skipListArenaChunkSize
+
+The number of bytes that we should use as chunk allocation for `org.apache.bookkeeper.bookie.SkipListArena`.
+
+**Default**: 4194304
+
+### skipListArenaMaxAllocSize
+
+The maximum size that we should allocate from the skiplist arena. Allocations larger than this should be allocated directly by the VM to avoid fragmentation.
+
+**Default**: 131072
+
+### bookieAuthProviderFactoryClass
+
+The factory class name of the bookie authentication provider. If this is null, then there is no authentication.
+
+**Default**: null
+
+### statsProviderClass
+
+ [...]
+
+ [...]
+
+### prometheusStatsHttpPort
+
+ [...]
+
+ [...]
+
+### dbStorage_writeCacheMaxSizeMb
+
+Size of Write Cache. Memory is allocated from JVM direct memory. Write cache is used to buffer entries before flushing into the entry log. For good performance, it should be big enough to hold a substantial amount of entries in the flush interval.
+
+**Default**: 25% of direct memory
+
+### dbStorage_readAheadCacheMaxSizeMb
+
+Size of Read cache. Memory is allocated from JVM direct memory. This read cache is pre-filled doing read-ahead whenever a cache miss happens. By default, it is allocated to 25% of the available direct memory.
+
+**Default**: N/A
+
+### dbStorage_readAheadCacheBatchSize
+
+How many entries to pre-fill in cache after a read cache miss
+
+**Default**: 1000
+
+### dbStorage_rocksDB_blockCacheSize
+
+Size of RocksDB block-cache. For best performance, this cache should be big enough to hold a significant portion of the index database which can reach ~2GB in some cases. By default, it uses 10% of direct memory.
+
+**Default**: N/A
+
+### dbStorage_rocksDB_writeBufferSizeMB
+
+**Default**: 64
+
+### dbStorage_rocksDB_sstSizeInMB
+
+**Default**: 64
+
+### dbStorage_rocksDB_blockSize
+
+**Default**: 65536
+
+### dbStorage_rocksDB_bloomFilterBitsPerKey
+
+**Default**: 10
+
+### dbStorage_rocksDB_numLevels
+
+**Default**: -1
+
+### dbStorage_rocksDB_numFilesInLevel0
+
+**Default**: 4
+
+### dbStorage_rocksDB_maxSizeInLevel1MB
+
+**Default**: 256
diff --git a/site2/website-next/static/reference/next/config/reference-configuration-log4j-shell.md b/site2/website-next/static/reference/next/config/reference-configuration-log4j-shell.md
new file mode 100644
index 00000000000..43fca015c0d
--- /dev/null
+++ b/site2/website-next/static/reference/next/config/reference-configuration-log4j-shell.md
@@ -0,0 +1,37 @@
+# Log4j shell
+
+### bookkeeper.root.logger
+
+**Default**: ERROR,CONSOLE
+
+### log4j.rootLogger
+
+**Default**: ${bookkeeper.root.logger}
+
+### log4j.appender.CONSOLE
+
+**Default**: org.apache.log4j.ConsoleAppender
+
+### log4j.appender.CONSOLE.Threshold
+
+**Default**: DEBUG
+
+### log4j.appender.CONSOLE.layout
+
+**Default**: org.apache.log4j.PatternLayout
+
+### log4j.appender.CONSOLE.layout.ConversionPattern
+
+**Default**: %d{ABSOLUTE} %-5p %m%n
+
+### log4j.logger.org.apache.zookeeper
+
+**Default**: ERROR
+
+### log4j.logger.org.apache.bookkeeper
+
+**Default**: ERROR
+
+### log4j.logger.org.apache.bookkeeper.bookie.BookieShell
+
+**Default**: INFO
diff --git a/site2/website-next/static/reference/next/config/reference-configuration-log4j.md b/site2/website-next/static/reference/next/config/reference-configuration-log4j.md
new file mode 100644
index 00000000000..6aa18e03a23
--- /dev/null
+++ b/site2/website-next/static/reference/next/config/reference-configuration-log4j.md
@@ -0,0 +1,80 @@
+# Log4j
+
+You can set the log level and configuration in the [log4j2.yaml](https://github.com/apache/pulsar/blob/d557e0aa286866363bc6261dec87790c055db1b0/conf/log4j2.yaml#L155) file. The following logging configuration parameters are available.
+
+### pulsar.root.logger
+
+**Default**: WARN,CONSOLE
+
+### pulsar.log.dir
+
+**Default**: logs
+
+### pulsar.log.file
+
+**Default**: pulsar.log
+
+### log4j.rootLogger
+
+**Default**: ${pulsar.root.logger}
+
+### log4j.appender.CONSOLE
+
+**Default**: org.apache.log4j.ConsoleAppender
+
+### log4j.appender.CONSOLE.Threshold
+
+**Default**: DEBUG
+
+### log4j.appender.CONSOLE.layout
+
+**Default**: org.apache.log4j.PatternLayout
+
+### log4j.appender.CONSOLE.layout.ConversionPattern
+
+**Default**: %d{ISO8601} - %-5p - [%t:%C{1}@%L] - %m%n
+
+### log4j.appender.ROLLINGFILE
+
+**Default**: org.apache.log4j.DailyRollingFileAppender
+
+### log4j.appender.ROLLINGFILE.Threshold
+
+**Default**: DEBUG
+
+### log4j.appender.ROLLINGFILE.File
+
+**Default**: ${pulsar.log.dir}/${pulsar.log.file}
+
+### log4j.appender.ROLLINGFILE.layout
+
+**Default**: org.apache.log4j.PatternLayout
+
+### log4j.appender.ROLLINGFILE.layout.ConversionPattern
+
+**Default**: %d{ISO8601} - %-5p [%t:%C{1}@%L] - %m%n
+
+### log4j.appender.TRACEFILE
+
+**Default**: org.apache.log4j.FileAppender
+
+### log4j.appender.TRACEFILE.Threshold
+
+**Default**: TRACE
+
+### log4j.appender.TRACEFILE.File
+
+**Default**: pulsar-trace.log
+
+### log4j.appender.TRACEFILE.layout
+
+**Default**: org.apache.log4j.PatternLayout
+
+### log4j.appender.TRACEFILE.layout.ConversionPattern
+
+**Default**: %d{ISO8601} - %-5p [%t:%C{1}@%L][%x] - %m%n
+
+> Note: 'topic' in log4j2.appender is configurable.
+>
+> - If you want to append all logs to a single topic, set the same topic name.
+> - If you want to append logs to different topics, you can set different topic names.
diff --git a/site2/website-next/static/reference/next/config/reference-configuration-zookeeper.md b/site2/website-next/static/reference/next/config/reference-configuration-zookeeper.md
new file mode 100644
index 00000000000..0e4b6b43f54
--- /dev/null
+++ b/site2/website-next/static/reference/next/config/reference-configuration-zookeeper.md
@@ -0,0 +1,83 @@
+# ZooKeeper
+
+ZooKeeper handles a broad range of essential configuration- and coordination-related tasks for Pulsar. The default configuration file for ZooKeeper is in the `conf/zookeeper.conf` file in your Pulsar installation. The following parameters are available:
+
+### tickTime
+
+The tick is the basic unit of time in ZooKeeper, measured in milliseconds and used to regulate things like heartbeats and timeouts. tickTime is the length of a single tick.
+
+**Default**: 2000
+
+### initLimit
+
+The maximum time, in ticks, that the leader ZooKeeper server allows follower ZooKeeper servers to successfully connect and sync. The tick time is set in milliseconds using the tickTime parameter.
+
+**Default**: 10
+
+### syncLimit
+
+The maximum time, in ticks, that a follower ZooKeeper server is allowed to sync with other ZooKeeper servers. The tick time is set in milliseconds using the tickTime parameter.
+
+**Default**: 5
+
+### dataDir
+
+The location where ZooKeeper will store in-memory database snapshots as well as the transaction log of updates to the database.
+
+**Default**: data/zookeeper
+
+### clientPort
+
+The port on which the ZooKeeper server will listen for connections.
+
+**Default**: 2181
+
+### admin.enableServer
+
+The port at which the admin listens.
+
+**Default**: true
+
+### admin.serverPort
+
+The port at which the admin listens.
+
+**Default**: 9990
+
+### autopurge.snapRetainCount
+
+In ZooKeeper, auto purge determines how many recent snapshots of the database stored in dataDir to retain within the time interval specified by autopurge.purgeInterval (while deleting the rest).
+
+**Default**: 3
+
+### autopurge.purgeInterval
+
+The time interval, in hours, by which the ZooKeeper database purge task is triggered. Setting to a non-zero number will enable auto purge; setting to 0 will disable. Read this guide before enabling auto purge.
+
+**Default**: 1
+
+### forceSync
+
+Requires updates to be synced to media of the transaction log before finishing processing the update. If this option is set to 'no', ZooKeeper will not require updates to be synced to the media. WARNING: it's not recommended to run a production ZK cluster with `forceSync` disabled.
+
+**Default**: yes
+
+### maxClientCnxns
+
+The maximum number of client connections. Increase this if you need to handle more ZooKeeper clients.
+
+**Default**: 60
+
+---
+
+In addition to the parameters above, configuring ZooKeeper for Pulsar involves adding a `server.N` line to the `conf/zookeeper.conf` file for each node in the ZooKeeper cluster, where `N` is the number of the ZooKeeper node. Here's an example of a three-node ZooKeeper cluster:
+
+```properties
+
+server.1=zk1.us-west.example.com:2888:3888
+server.2=zk2.us-west.example.com:2888:3888
+server.3=zk3.us-west.example.com:2888:3888
+
+```
+
+> We strongly recommend consulting the [ZooKeeper Administrator's Guide](https://zookeeper.apache.org/doc/current/zookeeperAdmin.html) for a more thorough and comprehensive introduction to ZooKeeper configuration