This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 269c88510a1 [feat][doc] Add various doc contribution guides (#18071)
269c88510a1 is described below
commit 269c88510a10e3f8e51f9bf00672d2ed4a67b02a
Author: Anonymitaet <[email protected]>
AuthorDate: Wed Oct 19 09:16:58 2022 +0800
[feat][doc] Add various doc contribution guides (#18071)
---
site2/README.md | 39 +++-
site2/doc-guides/assets/contribution-1.png | Bin 0 -> 71797 bytes
site2/doc-guides/assets/contribution-2.png | Bin 0 -> 52487 bytes
site2/doc-guides/assets/contribution-3.png | Bin 0 -> 64610 bytes
site2/doc-guides/assets/naming-1.png | Bin 0 -> 117563 bytes
site2/doc-guides/assets/preview-1.png | Bin 0 -> 139893 bytes
site2/doc-guides/assets/preview-2.png | Bin 0 -> 126997 bytes
site2/doc-guides/assets/syntax-1.png | Bin 0 -> 160167 bytes
site2/doc-guides/assets/syntax-10.png | Bin 0 -> 149702 bytes
site2/doc-guides/assets/syntax-11.png | Bin 0 -> 106124 bytes
site2/doc-guides/assets/syntax-12.png | Bin 0 -> 44427 bytes
site2/doc-guides/assets/syntax-13.png | Bin 0 -> 172770 bytes
site2/doc-guides/assets/syntax-2.png | Bin 0 -> 38032 bytes
site2/doc-guides/assets/syntax-3.png | Bin 0 -> 358193 bytes
site2/doc-guides/assets/syntax-4.png | Bin 0 -> 243160 bytes
site2/doc-guides/assets/syntax-5.png | Bin 0 -> 53777 bytes
site2/doc-guides/assets/syntax-6.png | Bin 0 -> 315928 bytes
site2/doc-guides/assets/syntax-7.png | Bin 0 -> 83816 bytes
site2/doc-guides/assets/syntax-8.png | Bin 0 -> 161006 bytes
site2/doc-guides/assets/syntax-9.png | Bin 0 -> 151067 bytes
site2/doc-guides/contribution.md | 215 +++++++++++++++++++++
site2/doc-guides/label.md | 19 ++
site2/doc-guides/naming.md | 211 +++++++++++++++++++++
site2/doc-guides/preview.md | 164 ++++++++++++++++
site2/doc-guides/syntax.md | 295 +++++++++++++++++++++++++++++
25 files changed, 942 insertions(+), 1 deletion(-)
diff --git a/site2/README.md b/site2/README.md
index 4405a9d2106..7b1ec17dfea 100644
--- a/site2/README.md
+++ b/site2/README.md
@@ -1 +1,38 @@
-For how to make contributions to Pulsar documentation and website, see [Pulsar
Documentation Contribution
Guide](https://docs.google.com/document/d/11DTnNPpvcPrebLkMAFcDEIFlD8ARD-k6F-LXoIwdD9Y/edit#).
\ No newline at end of file
+# Pulsar Documentation Contribution Overview
+
+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](./doc-guides/contribution.md)
+ * Doc structure and project organization
+ * Workflow of submitting various docs
+
+## Writing docs
+
+* [Pulsar Documentation Writing Syntax Guide](./doc-guides/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](./doc-guides/preview.md)
+
+## Preparing to submit doc PRs
+
+* [Pulsar Pull Request Naming Convention Guide](./doc-guides/naming.md)
+
+* [Pulsar Documentation Label Guide](./doc-guides/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/doc-guides/assets/contribution-1.png
b/site2/doc-guides/assets/contribution-1.png
new file mode 100644
index 00000000000..7363851e8bd
Binary files /dev/null and b/site2/doc-guides/assets/contribution-1.png differ
diff --git a/site2/doc-guides/assets/contribution-2.png
b/site2/doc-guides/assets/contribution-2.png
new file mode 100644
index 00000000000..998747a6ef5
Binary files /dev/null and b/site2/doc-guides/assets/contribution-2.png differ
diff --git a/site2/doc-guides/assets/contribution-3.png
b/site2/doc-guides/assets/contribution-3.png
new file mode 100644
index 00000000000..bf4c5fc180e
Binary files /dev/null and b/site2/doc-guides/assets/contribution-3.png differ
diff --git a/site2/doc-guides/assets/naming-1.png
b/site2/doc-guides/assets/naming-1.png
new file mode 100644
index 00000000000..1e6bdc44207
Binary files /dev/null and b/site2/doc-guides/assets/naming-1.png differ
diff --git a/site2/doc-guides/assets/preview-1.png
b/site2/doc-guides/assets/preview-1.png
new file mode 100644
index 00000000000..3c60383177f
Binary files /dev/null and b/site2/doc-guides/assets/preview-1.png differ
diff --git a/site2/doc-guides/assets/preview-2.png
b/site2/doc-guides/assets/preview-2.png
new file mode 100644
index 00000000000..b291fc6c825
Binary files /dev/null and b/site2/doc-guides/assets/preview-2.png differ
diff --git a/site2/doc-guides/assets/syntax-1.png
b/site2/doc-guides/assets/syntax-1.png
new file mode 100644
index 00000000000..17dbb33b4fe
Binary files /dev/null and b/site2/doc-guides/assets/syntax-1.png differ
diff --git a/site2/doc-guides/assets/syntax-10.png
b/site2/doc-guides/assets/syntax-10.png
new file mode 100644
index 00000000000..e01122a5ca0
Binary files /dev/null and b/site2/doc-guides/assets/syntax-10.png differ
diff --git a/site2/doc-guides/assets/syntax-11.png
b/site2/doc-guides/assets/syntax-11.png
new file mode 100644
index 00000000000..d8ba64d99bd
Binary files /dev/null and b/site2/doc-guides/assets/syntax-11.png differ
diff --git a/site2/doc-guides/assets/syntax-12.png
b/site2/doc-guides/assets/syntax-12.png
new file mode 100644
index 00000000000..d50bfb00716
Binary files /dev/null and b/site2/doc-guides/assets/syntax-12.png differ
diff --git a/site2/doc-guides/assets/syntax-13.png
b/site2/doc-guides/assets/syntax-13.png
new file mode 100644
index 00000000000..56a8cdfd79a
Binary files /dev/null and b/site2/doc-guides/assets/syntax-13.png differ
diff --git a/site2/doc-guides/assets/syntax-2.png
b/site2/doc-guides/assets/syntax-2.png
new file mode 100644
index 00000000000..7a2a11cd1cb
Binary files /dev/null and b/site2/doc-guides/assets/syntax-2.png differ
diff --git a/site2/doc-guides/assets/syntax-3.png
b/site2/doc-guides/assets/syntax-3.png
new file mode 100644
index 00000000000..b1026a6eb6d
Binary files /dev/null and b/site2/doc-guides/assets/syntax-3.png differ
diff --git a/site2/doc-guides/assets/syntax-4.png
b/site2/doc-guides/assets/syntax-4.png
new file mode 100644
index 00000000000..f13005e39c4
Binary files /dev/null and b/site2/doc-guides/assets/syntax-4.png differ
diff --git a/site2/doc-guides/assets/syntax-5.png
b/site2/doc-guides/assets/syntax-5.png
new file mode 100644
index 00000000000..19cdbfc261c
Binary files /dev/null and b/site2/doc-guides/assets/syntax-5.png differ
diff --git a/site2/doc-guides/assets/syntax-6.png
b/site2/doc-guides/assets/syntax-6.png
new file mode 100644
index 00000000000..aec5e6bb13b
Binary files /dev/null and b/site2/doc-guides/assets/syntax-6.png differ
diff --git a/site2/doc-guides/assets/syntax-7.png
b/site2/doc-guides/assets/syntax-7.png
new file mode 100644
index 00000000000..15ad9b013ab
Binary files /dev/null and b/site2/doc-guides/assets/syntax-7.png differ
diff --git a/site2/doc-guides/assets/syntax-8.png
b/site2/doc-guides/assets/syntax-8.png
new file mode 100644
index 00000000000..401222d3278
Binary files /dev/null and b/site2/doc-guides/assets/syntax-8.png differ
diff --git a/site2/doc-guides/assets/syntax-9.png
b/site2/doc-guides/assets/syntax-9.png
new file mode 100644
index 00000000000..6c38d48f8eb
Binary files /dev/null and b/site2/doc-guides/assets/syntax-9.png differ
diff --git a/site2/doc-guides/contribution.md b/site2/doc-guides/contribution.md
new file mode 100644
index 00000000000..14d5e8dcaec
--- /dev/null
+++ b/site2/doc-guides/contribution.md
@@ -0,0 +1,215 @@
+# Pulsar Documentation Contribution Guide
+
+> 👩🏻🏫 **Summary**
+>
+> This guide explains the organization of Pulsar documentation and website
repos and the workflow of updating various Pulsar docs.
+
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Contribution
Guide](#pulsar-documentation-contribution-guide)
+ - [Documentation and website repos](#documentation-and-website-repos)
+ - [Intro to doc and website repos](#intro-to-doc-and-website-repos)
+ - [Relationships between doc and website
repos](#relationships-between-doc-and-website-repos)
+ - [Update versioned docs](#update-versioned-docs)
+ - [Update reference docs](#update-reference-docs)
+ - [Update Pulsar configuration docs](#update-pulsar-configuration-docs)
+ - [Update client configuration docs](#update-client-configuration-docs)
+ - [Update CLI tool docs](#update-cli-tool-docs)
+ - [Update client/function matrix](#update-clientfunction-matrix)
+ - [References](#references)
+
+<!-- /TOC -->
+
+## 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://github.com/apache/pulsar-site/pull/108)
+
+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>.
+ </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>.
+ </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
`[email protected]` 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).
\ No newline at end of file
diff --git a/site2/doc-guides/label.md b/site2/doc-guides/label.md
new file mode 100644
index 00000000000..816c5aec8cf
--- /dev/null
+++ b/site2/doc-guides/label.md
@@ -0,0 +1,19 @@
+# Pulsar Documentation Label Guide
+
+> 👩🏻🏫 **Summary**
+>
+> 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 name|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` ❌
+
+## References
+
+For more guides on how to make contributions to Pulsar docs, see [Pulsar
Documentation Contribution Overview](./../README.md).
\ No newline at end of file
diff --git a/site2/doc-guides/naming.md b/site2/doc-guides/naming.md
new file mode 100644
index 00000000000..f46f7d3a02d
--- /dev/null
+++ b/site2/doc-guides/naming.md
@@ -0,0 +1,211 @@
+# Pulsar Pull Request Naming Convention Guide
+
+> 👩🏻🏫 **Summary**
+>
+> This guide explains why you need good PR titles and how you do that with
various self-explanatory examples.
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Pull Request Naming Convention
Guide](#pulsar-pull-request-naming-convention-guide)
+ - [Why do PR titles matter?](#why-do-pr-titles-matter)
+ - [How to write good PR titles?](#how-to-write-good-pr-titles)
+ - [💡Quick examples](#💡quick-examples)
+ - [`type`](#type)
+ - [`scope`](#scope)
+ - [Pulsar](#pulsar)
+ - [Client](#client)
+ - [`Summary`](#summary)
+ - [Full examples](#full-examples)
+ - [References](#references)
+
+<!-- /TOC -->
+
+## 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
+
+## References
+
+For more guides on how to make contributions to Pulsar docs, see [Pulsar
Documentation Contribution Overview](./../README.md).
\ No newline at end of file
diff --git a/site2/doc-guides/preview.md b/site2/doc-guides/preview.md
new file mode 100644
index 00000000000..ae4c561c6b0
--- /dev/null
+++ b/site2/doc-guides/preview.md
@@ -0,0 +1,164 @@
+# Pulsar Content Preview Guide
+
+> 👩🏻🏫 **Summary**
+>
+> This guide explains why and how to preview Pulsar content locally with
detailed steps and various examples.
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Content Preview Guide](#pulsar-content-preview-guide)
+ - [Why preview changes locally?](#why-preview-changes-locally)
+ - [How to preview changes locally?](#how-to-preview-changes-locally)
+ - [Prerequisites](#prerequisites)
+ - [Preview doc (markdown) changes](#preview-doc-markdown-changes)
+ - [Preview doc (Java API) changes](#preview-doc-java-api-changes)
+ - [Preview website changes](#preview-website-changes)
+ - [Stop preview](#stop-preview)
+ - [Maintenance info](#maintenance-info)
+ - [References](#references)
+
+<!-- /TOC -->
+
+## 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.
+
+
+ ```
+ cd pulsar/site2/website
+ ```
+
+2. Run the following command to preview changes.
+
+* Preview **master** changes
+
+ If you update master docs, use the following command.
+
+ ```
+ 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.
+
+ ```
+ sh start.sh <version-number> <version-number>
+ ```
+
+ 
+
+3. By default, a browser window will open at
[http://localhost:3000](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.
+
+ ```
+ cd pulsar/site2/tools
+ ```
+
+2. Run the following command to generate the `.html` files.
+
+ ```
+ 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.
+
+ ```
+ 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.
+
+
+ ```
+ ./preview.sh
+ ```
+
+ * Preview **historical** changes
+
+ ```
+ ./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.
+
+## References
+
+For more guides on how to make contributions to Pulsar docs, see [Pulsar
Documentation Contribution Overview](./../README.md).
\ No newline at end of file
diff --git a/site2/doc-guides/syntax.md b/site2/doc-guides/syntax.md
new file mode 100644
index 00000000000..8c1cab39362
--- /dev/null
+++ b/site2/doc-guides/syntax.md
@@ -0,0 +1,295 @@
+# Pulsar Documentation Writing Syntax Guide
+
+> 👩🏻🏫 **Summary**
+>
+> This guide explains how to write Pulsar documentation using the
MDX-compatible markdown syntax.
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Writing Syntax
Guide](#pulsar-documentation-writing-syntax-guide)
+ - [Background](#background)
+ - [Why use new markdown syntax?](#why-use-new-markdown-syntax)
+ - [How to test doc changes?](#how-to-test-doc-changes)
+ - [Syntax](#syntax)
+ - [Markdown](#markdown)
+ - [Tab](#tab)
+ - [Code blocks](#code-blocks)
+ - [Admonitions](#admonitions)
+ - [Assets](#assets)
+ - [Indentation & space](#indentation--space)
+ - [Metadata](#metadata)
+ - [Tables](#tables)
+ - [Links](#links)
+ - [Anchor links](#anchor-links)
+ - [Links to internal documentation](#links-to-internal-documentation)
+ - [Links to external documentation](#links-to-external-documentation)
+ - [Link to a specific line of code](#link-to-a-specific-line-of-code)
+ - [Authoritative sources](#authoritative-sources)
+ - [Escape](#escape)
+ - [Headings](#headings)
+ - [References](#references)
+
+<!-- /TOC -->
+
+## 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.
+
+## References
+
+For more guides on how to make contributions to Pulsar docs, see [Pulsar
Documentation Contribution Overview](./../README.md).
\ No newline at end of file
