This is an automated email from the ASF dual-hosted git repository.
penghui 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 bb501f9764e Introduce the first version of contribution guide (#268)
bb501f9764e is described below
commit bb501f9764ea4f3496904f896a41ee6a10f2e900
Author: tison <[email protected]>
AuthorDate: Mon Oct 31 16:50:45 2022 +0800
Introduce the first version of contribution guide (#268)
---
site2/website-next/contribute/about.md | 17 +
.../contribute/committer-guide/_category_.json | 7 +
.../become-a-committer-or-pmc-member.md | 23 +
.../contribute/documentation/_category_.json | 7 +
.../documentation/assets/contribution-1.png | Bin 0 -> 71797 bytes
.../documentation/assets/contribution-2.png | Bin 0 -> 52487 bytes
.../documentation/assets/contribution-3.png | Bin 0 -> 64610 bytes
.../contribute/documentation/assets/naming-1.png | Bin 0 -> 117563 bytes
.../contribute/documentation/assets/preview-1.png | Bin 0 -> 139893 bytes
.../contribute/documentation/assets/preview-2.png | Bin 0 -> 126997 bytes
.../contribute/documentation/assets/syntax-1.png | Bin 0 -> 160167 bytes
.../contribute/documentation/assets/syntax-10.png | Bin 0 -> 149702 bytes
.../contribute/documentation/assets/syntax-11.png | Bin 0 -> 106124 bytes
.../contribute/documentation/assets/syntax-12.png | Bin 0 -> 44427 bytes
.../contribute/documentation/assets/syntax-13.png | Bin 0 -> 172770 bytes
.../contribute/documentation/assets/syntax-2.png | Bin 0 -> 38032 bytes
.../contribute/documentation/assets/syntax-3.png | Bin 0 -> 358193 bytes
.../contribute/documentation/assets/syntax-4.png | Bin 0 -> 243160 bytes
.../contribute/documentation/assets/syntax-5.png | Bin 0 -> 53777 bytes
.../contribute/documentation/assets/syntax-6.png | Bin 0 -> 315928 bytes
.../contribute/documentation/assets/syntax-7.png | Bin 0 -> 83816 bytes
.../contribute/documentation/assets/syntax-8.png | Bin 0 -> 161006 bytes
.../contribute/documentation/assets/syntax-9.png | Bin 0 -> 151067 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 +
.../contribute/getting-started/setup-building.md | 61 ++
.../contribute/getting-started/setup-ide.md | 96 ++++
.../contribute/releasing/_category_.json | 7 +
.../contribute/releasing/create-gpg-keys.md | 140 +++++
.../releasing/release-note-guide-example-1.png | Bin 0 -> 273286 bytes
.../contribute/releasing/release-note-guide.md | 57 ++
.../contribute/releasing/release-process.md | 570 +++++++++++++++++++
.../releasing/validate-release-candidate.md | 630 +++++++++++++++++++++
.../contribute/testing-and-ci/_category_.json | 7 +
.../testing-and-ci/ci-testing-in-fork.md | 63 +++
.../contribute/testing-and-ci/licensing.md | 11 +
site2/website-next/docusaurus.config.js | 17 +
site2/website-next/sidebarsContribute.js | 6 +
site2/website-next/src/pages/coding-guide.md | 4 +-
site2/website-next/src/pages/contributing.md | 16 +-
site2/website-next/src/pages/markdown-page.md | 7 -
46 files changed, 2559 insertions(+), 17 deletions(-)
diff --git a/site2/website-next/contribute/about.md
b/site2/website-next/contribute/about.md
new file mode 100644
index 00000000000..ebd75f8dddf
--- /dev/null
+++ b/site2/website-next/contribute/about.md
@@ -0,0 +1,17 @@
+---
+slug: /
+id: about
+title: Apache Pulsar Contribution Guide
+sidebar_label: "About"
+sidebar_position: 2
+---
+
+This guide is a comprehensive resource for contributing to Apache Pulsar – for
both new and experienced contributors. It is maintained by the same community
that maintains Pulsar. We welcome your contributions to Pulsar!
+
+## Quick Links
+
+Here are some links that you probably will reference frequently while
contributing to Pulsar:
+
+* [Issue tracker](https://github.com/apache/pulsar/issues)
+* [Developer mailing list](mailto:[email protected])
([subscribe](mailto:[email protected]))
+* [#contributors channel on Pulsar
Slack](https://apache-pulsar.slack.com/channels/contributors)
([join](https://pulsar.apache.org/community#section-discussions))
diff --git a/site2/website-next/contribute/committer-guide/_category_.json
b/site2/website-next/contribute/committer-guide/_category_.json
new file mode 100644
index 00000000000..00dcc986071
--- /dev/null
+++ b/site2/website-next/contribute/committer-guide/_category_.json
@@ -0,0 +1,7 @@
+{
+ "label": "Committer Guide",
+ "position": 999,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git
a/site2/website-next/contribute/committer-guide/become-a-committer-or-pmc-member.md
b/site2/website-next/contribute/committer-guide/become-a-committer-or-pmc-member.md
new file mode 100644
index 00000000000..f7c63ccb5b0
--- /dev/null
+++
b/site2/website-next/contribute/committer-guide/become-a-committer-or-pmc-member.md
@@ -0,0 +1,23 @@
+---
+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"
+---
+
+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.
+
+Being an active community member means participating on mailing list
discussions, helping to answer questions, verifying release candidates, being
respectful towards others, and following the meritocratic principles of
community management. Since [the Apache
Way](https://www.apache.org/theapacheway/index.html) has a strong focus on the
project community, this part is very important.
+
+Of course, contributing code and documentation to the project is important as
well. A good way to start is contributing improvements, new features, or bug
fixes. You need to show that you take responsibility for the code that you
contribute, add tests and documentation, and help maintaining it.
+
+Every new committer has to be proposed by a current committer and then
privately discussed and voted in by the members of the Pulsar PMC. For details
about this process and for candidate requirements see the general [Apache
guidelines for assessing new candidates for
committership](https://community.apache.org/newcommitter.html).
+
+Candidates prepare for their nomination as committer by contributing to the
Pulsar project and its community, by acting according to the Apache Way, and by
generally following the path from [contributor to
committer](https://community.apache.org/contributors/) for Apache projects.
+
+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.
+
+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/documentation/_category_.json
b/site2/website-next/contribute/documentation/_category_.json
new file mode 100644
index 00000000000..a3fdeed6253
--- /dev/null
+++ b/site2/website-next/contribute/documentation/_category_.json
@@ -0,0 +1,7 @@
+{
+ "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
new file mode 100644
index 00000000000..7363851e8bd
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/contribution-1.png differ
diff --git
a/site2/website-next/contribute/documentation/assets/contribution-2.png
b/site2/website-next/contribute/documentation/assets/contribution-2.png
new file mode 100644
index 00000000000..998747a6ef5
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/contribution-2.png differ
diff --git
a/site2/website-next/contribute/documentation/assets/contribution-3.png
b/site2/website-next/contribute/documentation/assets/contribution-3.png
new file mode 100644
index 00000000000..bf4c5fc180e
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/contribution-3.png differ
diff --git a/site2/website-next/contribute/documentation/assets/naming-1.png
b/site2/website-next/contribute/documentation/assets/naming-1.png
new file mode 100644
index 00000000000..1e6bdc44207
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/naming-1.png differ
diff --git a/site2/website-next/contribute/documentation/assets/preview-1.png
b/site2/website-next/contribute/documentation/assets/preview-1.png
new file mode 100644
index 00000000000..3c60383177f
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/preview-1.png differ
diff --git a/site2/website-next/contribute/documentation/assets/preview-2.png
b/site2/website-next/contribute/documentation/assets/preview-2.png
new file mode 100644
index 00000000000..b291fc6c825
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/preview-2.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-1.png
b/site2/website-next/contribute/documentation/assets/syntax-1.png
new file mode 100644
index 00000000000..17dbb33b4fe
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-1.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-10.png
b/site2/website-next/contribute/documentation/assets/syntax-10.png
new file mode 100644
index 00000000000..e01122a5ca0
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-10.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-11.png
b/site2/website-next/contribute/documentation/assets/syntax-11.png
new file mode 100644
index 00000000000..d8ba64d99bd
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-11.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-12.png
b/site2/website-next/contribute/documentation/assets/syntax-12.png
new file mode 100644
index 00000000000..d50bfb00716
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-12.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-13.png
b/site2/website-next/contribute/documentation/assets/syntax-13.png
new file mode 100644
index 00000000000..56a8cdfd79a
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-13.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-2.png
b/site2/website-next/contribute/documentation/assets/syntax-2.png
new file mode 100644
index 00000000000..7a2a11cd1cb
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-2.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-3.png
b/site2/website-next/contribute/documentation/assets/syntax-3.png
new file mode 100644
index 00000000000..b1026a6eb6d
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-3.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-4.png
b/site2/website-next/contribute/documentation/assets/syntax-4.png
new file mode 100644
index 00000000000..f13005e39c4
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-4.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-5.png
b/site2/website-next/contribute/documentation/assets/syntax-5.png
new file mode 100644
index 00000000000..19cdbfc261c
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-5.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-6.png
b/site2/website-next/contribute/documentation/assets/syntax-6.png
new file mode 100644
index 00000000000..aec5e6bb13b
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-6.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-7.png
b/site2/website-next/contribute/documentation/assets/syntax-7.png
new file mode 100644
index 00000000000..15ad9b013ab
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-7.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-8.png
b/site2/website-next/contribute/documentation/assets/syntax-8.png
new file mode 100644
index 00000000000..401222d3278
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-8.png differ
diff --git a/site2/website-next/contribute/documentation/assets/syntax-9.png
b/site2/website-next/contribute/documentation/assets/syntax-9.png
new file mode 100644
index 00000000000..6c38d48f8eb
Binary files /dev/null and
b/site2/website-next/contribute/documentation/assets/syntax-9.png differ
diff --git a/site2/website-next/contribute/documentation/contribution.md
b/site2/website-next/contribute/documentation/contribution.md
new file mode 100644
index 00000000000..a775d3331bb
--- /dev/null
+++ b/site2/website-next/contribute/documentation/contribution.md
@@ -0,0 +1,195 @@
+---
+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
`[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).
diff --git a/site2/website-next/contribute/documentation/label.md
b/site2/website-next/contribute/documentation/label.md
new file mode 100644
index 00000000000..8f170a61fdb
--- /dev/null
+++ b/site2/website-next/contribute/documentation/label.md
@@ -0,0 +1,17 @@
+---
+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
new file mode 100644
index 00000000000..6d1b7cdd875
--- /dev/null
+++ b/site2/website-next/contribute/documentation/naming.md
@@ -0,0 +1,173 @@
+---
+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
new file mode 100644
index 00000000000..ee6c615ba6c
--- /dev/null
+++ b/site2/website-next/contribute/documentation/overview.md
@@ -0,0 +1,38 @@
+---
+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
new file mode 100644
index 00000000000..e0b9ac3d9aa
--- /dev/null
+++ b/site2/website-next/contribute/documentation/preview.md
@@ -0,0 +1,142 @@
+---
+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
new file mode 100644
index 00000000000..c6af3a20174
--- /dev/null
+++ b/site2/website-next/contribute/documentation/syntax.md
@@ -0,0 +1,258 @@
+---
+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
new file mode 100644
index 00000000000..1670452b96b
--- /dev/null
+++ b/site2/website-next/contribute/getting-started/_category_.json
@@ -0,0 +1,7 @@
+{
+ "label": "Getting Started",
+ "position": 3,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git a/site2/website-next/contribute/getting-started/setup-building.md
b/site2/website-next/contribute/getting-started/setup-building.md
new file mode 100644
index 00000000000..66600b49155
--- /dev/null
+++ b/site2/website-next/contribute/getting-started/setup-building.md
@@ -0,0 +1,61 @@
+---
+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+.
|
+| Zip | The build process requires Zip as a utility tool.
|
+
+:::note
+
+This project includes a [Maven Wrapper](https://maven.apache.org/wrapper/)
that can be used instead of a system installed Maven. Use it by replacing `mvn`
with `./mvnw` on Linux and `mvnw.cmd` on Windows in the commands below.
+
+:::
+
+## Clone
+
+Clone the source code to your development machine:
+
+```bash
+git clone https://github.com/apache/pulsar
+```
+
+## Build
+
+Compile and install:
+
+```bash
+mvn clean install -DskipTests
+```
+
+## Run unit tests
+
+```bash
+mvn test
+```
+
+Run individual unit test:
+
+```bash
+# mvn -pl <module-name> test -Dtest=<unit-test-name> # for example:
+mvn -pl pulsar-client test -Dtest=ConsumerBuilderImplTest
+```
+
+## Start standalone Pulsar service
+
+```bash
+bin/pulsar standalone
+```
+
+## Connect to the standalone service:
+
+```bash
+bin/pulsar-shell
+```
diff --git a/site2/website-next/contribute/getting-started/setup-ide.md
b/site2/website-next/contribute/getting-started/setup-ide.md
new file mode 100644
index 00000000000..37cf82734c3
--- /dev/null
+++ b/site2/website-next/contribute/getting-started/setup-ide.md
@@ -0,0 +1,96 @@
+---
+id: setup-ide
+title: Setup IDE
+sidebar_label: "Setup IDE"
+---
+
+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
+
+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**. You can pick a version from
many vendors. Unless you have a specific preference, choose **Eclipse Temurin
(AdoptOpenJDK (Hotspot))**.
+
+### 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
+
+1. Open Annotation Processors Settings dialog box by going to **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. 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".
+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**
+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**.
+
+### Configure Checkstyle
+
+1. Install the Checkstyle-IDEA plugin.
+2. Open Checkstyle Settings dialog box by going to **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.
+ 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**.
+6. Activate the configuration you just added by toggling the corresponding box.
+7. Click **OK**.
+
+### Further configuration in IntelliJ
+
+* 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"
+ * Activate "core-modules" Maven profile
+ * De-activate "main" Maven profile
+ * 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
+
+* 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.
+ * 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.
+* The above steps have all been performed, but a test still won't run.
+ * In this case, try the following steps:
+ 1. Close IntelliJ.
+ 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.
+ 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.
diff --git a/site2/website-next/contribute/releasing/_category_.json
b/site2/website-next/contribute/releasing/_category_.json
new file mode 100644
index 00000000000..6def1d9c705
--- /dev/null
+++ b/site2/website-next/contribute/releasing/_category_.json
@@ -0,0 +1,7 @@
+{
+ "label": "Releasing",
+ "position": 5,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git a/site2/website-next/contribute/releasing/create-gpg-keys.md
b/site2/website-next/contribute/releasing/create-gpg-keys.md
new file mode 100644
index 00000000000..4c67bb36685
--- /dev/null
+++ b/site2/website-next/contribute/releasing/create-gpg-keys.md
@@ -0,0 +1,140 @@
+---
+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:
+
+```shell
+brew install gnupg
+```
+
+Set configuration to use `SHA512` keys by default:
+
+```shell
+mkdir ~/.gnupg
+cat <<EOL >> ~/.gnupg/gpg.conf
+personal-digest-preferences SHA512
+cert-digest-algo SHA512
+default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5
ZLIB BZIP2 ZIP Uncompressed
+EOL
+chmod 700 ~/.gnupg/gpg.conf
+```
+
+Check the version:
+
+```shell
+gpg --version
+
+# gpg (GnuPG) 2.1.22
+# ...
+```
+
+Generate new GPG key:
+
+```shell
+# For 1.x or 2.0.x
+gpg --gen-key
+
+# For 2.1.x
+gpg --full-gen-key
+
+gpg (GnuPG) 2.1.22; Copyright (C) 2017 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Please select what kind of key you want:
+ (1) RSA and RSA (default)
+ (2) DSA and Elgamal
+ (3) DSA (sign only)
+ (4) RSA (sign only)
+Your selection? 1
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) 4096
+Requested keysize is 4096 bits
+Please specify how long the key should be valid.
+ 0 = key does not expire
+ <n> = key expires in n days
+ <n>w = key expires in n weeks
+ <n>m = key expires in n months
+ <n>y = key expires in n years
+Key is valid for? (0) 0
+Key does not expire at all
+Is this correct? (y/N) y
+
+GnuPG needs to construct a user ID to identify your key.
+
+Real name: test user
+Email address: [email protected]
+Comment: CODE SIGNING KEY
+You selected this USER-ID:
+ "test user (CODE SIGNING KEY) <[email protected]>"
+
+Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
+<Enter passphrase>
+```
+
+:::note
+
+New **RSA** keys generated should be at least **4096** bits.
+
+:::
+
+## Appending the key to KEYS files
+
+The GPG key needs to be appended to `KEYS` file that is stored in 2 SVN
locations, one for proper releases and one for the release candidates.
+
+The credentials for SVN are the usual Apache account credentials.
+
+```shell
+# Checkout the SVN folder containing the KEYS file
+svn co https://dist.apache.org/repos/dist/dev/pulsar pulsar-dist-dev-keys
--depth empty
+cd pulsar-dist-dev-keys
+svn up KEYS
+
+APACHEID=apacheid
+# Export the key in ascii format and append it to the file
+( gpg --list-sigs [email protected]
+ gpg --export --armor [email protected] ) >> KEYS
+
+# Commit to SVN
+svn ci -m "Added gpg key for $APACHEID"
+```
+
+Repeat the same operation for the release KEYS file:
+
+:::warning
+
+You should ask a PMC member to complete this step.
+
+:::
+
+```shell
+# Checkout the SVN folder containing the KEYS file
+svn co https://dist.apache.org/repos/dist/release/pulsar
pulsar-dist-release-keys --depth empty
+cd pulsar-dist-release-keys
+svn up KEYS
+
+APACHEID=apacheid
+# Export the key in ascii format and append it to the file
+( gpg --list-sigs [email protected]
+ gpg --export --armor [email protected] ) >> KEYS
+
+# Commit to SVN
+svn ci -m "Added gpg key for $APACHEID"
+```
+
+## Upload the key to a public key server
+
+Use the key id to publish it to several public key servers:
+
+```shell
+gpg --send-key 8C75C738C33372AE198FD10CC238A8CAAC055FD2
+gpg --send-key --keyserver=keys.openpgp.org
8C75C738C33372AE198FD10CC238A8CAAC055FD2
+gpg --send-key --keyserver=keyserver.ubuntu.com
8C75C738C33372AE198FD10CC238A8CAAC055FD2
+```
diff --git
a/site2/website-next/contribute/releasing/release-note-guide-example-1.png
b/site2/website-next/contribute/releasing/release-note-guide-example-1.png
new file mode 100644
index 00000000000..25120c886e6
Binary files /dev/null and
b/site2/website-next/contribute/releasing/release-note-guide-example-1.png
differ
diff --git a/site2/website-next/contribute/releasing/release-note-guide.md
b/site2/website-next/contribute/releasing/release-note-guide.md
new file mode 100644
index 00000000000..4e61c14b5d0
--- /dev/null
+++ b/site2/website-next/contribute/releasing/release-note-guide.md
@@ -0,0 +1,57 @@
+---
+id: release-note-guide
+title: Release Note Guide
+sidebar_label: "Release Note Guide"
+---
+
+This guide explains everything about Pulsar release notes.
+
+## Intro to release notes
+
+This chapter gives an overview of Pulsar release notes.
+
+### Basic info
+
+[Pulsar release notes](https://pulsar.apache.org/release-notes/) consist of
the following parts.
+
+| Release note
| Component
|
+| ----------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------
|
+| [Pulsar Core](https://pulsar.apache.org/release-notes/#pulsar-release-notes)
| <div align="center">Pulsar</div>
|
+| [Pulsar Clients](../../site2/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
+
+For the [Pulsar Release Note page](https://pulsar.apache.org/release-notes/):
+
+* It is generated automatically using
[release-json-gen.sh](https://github.com/apache/pulsar-site/blob/main/site2/tools/release-json-gen.sh).
For implementation details, see [PIP 112: Generate Release Notes
Automatically](https://github.com/apache/pulsar/wiki/PIP-112:-Generate-Release-Notes-Automatically).
+* The info is fetched from the [Pulsar Releases Page -
GitHub](https://github.com/apache/pulsar/releases).
+* It is updated when one of the following conditions is met:
+ * *A commit is pushed to the [pulsar-site
repo](https://github.com/apache/pulsar-site).
+ * A [Pulsar site sync
job](https://github.com/apache/pulsar-site/actions/workflows/ci-pulsar-website-docs-sync.yaml)
is performed (every 6 hours).
+
+## Submit release notes
+
+Follow the steps below to submit release notes for Pulsar and clients (**Java
and WebSocket**).
+
+:::note
+
+For **C++, Python, Go, Node.js, and C#**, 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).
+
+:::
+
+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).
+2. Get this PR reviewed and merged.
+3. Copy the release note to the [Pulsar Releases Page -
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/).
+
+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.
diff --git a/site2/website-next/contribute/releasing/release-process.md
b/site2/website-next/contribute/releasing/release-process.md
new file mode 100644
index 00000000000..33c8e19ed8c
--- /dev/null
+++ b/site2/website-next/contribute/releasing/release-process.md
@@ -0,0 +1,570 @@
+---
+id: release-process
+title: Release Process
+sidebar_label: "Release Process"
+---
+
+This page contains instructions for Pulsar committers on how to perform a
release.
+
+:::note
+
+The term `major/minor releases` used throughout this document is defined as
follows:
+
+* Major releases refer to feature releases, such as 2.10.0, 2.11.0, and so on.
+* Minor releases refer to bug-fix releases, such as 2.10.1, 2.10.2, and so on.
+
+:::
+
+## Preparation
+
+Open a discussion in [email protected] to notify others that you volunteer to be
the release manager of a specific release. If there are no disagreements, you
can start the release process.
+
+For major releases, you should create a new branch named `branch-2.X.0` once
all PRs with the 2.X.0 milestone are merged. If some PRs with the 2.X.0
milestone are still working in progress and might take much time to complete,
you can move them to the next milestone if they are not important. In this
case, you'd better notify the author in the PR.
+
+For minor releases, if there are no disagreements, you should cherry-pick all
merged PRs with the `release/X.Y.Z` labels into `branch-X.Y`. After these PRs
are cherry-picked, you should add the `cherry-picked/branch-X.Y` labels.
+
+Sometimes some PRs cannot be cherry-picked cleanly, you might need to create a
separate PR and move the `release/X.Y.Z` label from the original PR to it. In
this case, you can ask the author to help create the new PR.
+
+For PRs that are still open, you can choose to delay them to the next release
or ping others to review so that they can be merged.
+
+To verify the release branch is not broken, you can synchronize the branch in
your private repo and open a PR to trigger the CI. Example:
https://github.com/BewareMyPower/pulsar/pull/3
+
+> You can use the following command to catch basic compilation or checkstyle
errors in your local env before cherry-picking.
+>
+> ```bash
+> mvn -Pcore-modules,-main -T 1C clean install -DskipTests -Dspotbugs.skip=true
+> ```
+
+## Requirements
+
+If you haven't already done it, [create and publish the GPG
key](https://github.com/apache/pulsar/blob/master/wiki/release/create-gpg-keys.md)
to sign the release artifacts.
+
+Before you start the next release steps, make sure you have installed the
**JDK8** and maven **3.6.1** for Pulsar 2.6 and Pulsar 2.7, and **JDK11** and
Maven **3.6.1** for Pulsar 2.8 onwards. And **clean up the bookkeeper's local
compiled** to make sure the bookkeeper dependency is fetched from the Maven
repo, details to see
https://lists.apache.org/thread/gsbh95b2d9xtcg5fmtxpm9k9q6w68gd2
+
+## Create the release branch
+
+We are going to create a branch from `master` to `branch-v2.X`
+where the tag will be generated and where new fixes will be
+applied as part of the maintenance for the release.
+
+The branch needs only to be created when creating major releases,
+and not for minor releases like `2.3.1`. For minor releases, go to the next
step.
+
+For example, when you create the `v2.3.0` release, the branch `branch-2.3`
will be created; but for `v2.3.1`, we
+keep using the old `branch-2.3`.
+
+In these instructions, I'm referring to a fictitious release `2.X.0`. Change
the release version in the examples accordingly with the real version.
+
+It is recommended to create a fresh clone of the repository to avoid any local
files interfering in the process:
+
+```shell
+git clone [email protected]:apache/pulsar.git
+cd pulsar
+git checkout -b branch-2.X origin/master
+```
+
+Alternatively, you can use a git workspace to create a new, clean directory on
your machine without needing to re-download the project.
+
+```shell
+git worktree add ../pulsar.branch-2.X branch-2.X
+```
+
+If you created a new branch, update the `CI - OWASP Dependency Check` workflow
so that it will run on the new branch. At the time of writing, here is the file
that should be updated:
https://github.com/apache/pulsar/blob/master/.github/workflows/ci-owasp-dependency-check.yaml.
+
+Note also that you should stop the GitHub action for Pulsar versions that are
EOL.
+
+Also, if you created a new branch, please update the `Security Policy and
Supported Versions` page on the website. This page has a table for support
timelines based on when minor releases take place.
+
+## Update project version and tag
+
+During the release process, you are going to initially create
+"candidate" tags, that after verification and approval will
+get promoted to the "real" final tag.
+
+In this process, the maven version of the project will always
+be the final one.
+
+```shell
+# Bump to the release version
+./src/set-project-version.sh 2.X.0
+
+# Some version may not update the right parent version of
`protobuf-shaded/pom.xml`, please double check it.
+
+# Commit
+git commit -m 'Release 2.X.0' -a
+
+# Create a "candidate" tag
+# If you don't sign your commits already, use the following
+export GPG_TTY=$(tty)
+git tag -u [email protected] v2.X.0-candidate-1 -m 'Release v2.X.0-candidate-1'
+# If you already sign your commits using your apache.org email, use the
following
+git tag -s v2.X.0-candidate-1 -m 'Release v2.X.0-candidate-1'
+
+# Verify that you signed your tag before pushing it:
+git tag -v v2.X.0-candidate-1
+
+# Push both the branch and the tag to Github repo
+git push origin branch-2.X
+git push origin v2.X.0-candidate-1
+```
+
+For minor releases, the tag is like `2.3.1`.
+
+## Build and inspect the artifacts
+
+```shell
+mvn clean install -DskipTests
+```
+
+After the build, there will be 4 generated artifacts:
+
+* `distribution/server/target/apache-pulsar-2.X.0-bin.tar.gz`
+* `target/apache-pulsar-2.X.0-src.tar.gz`
+* `distribution/offloaders/target/apache-pulsar-offloaders-2.X.0-bin.tar.gz`
+* directory `distribution/io/target/apache-pulsar-io-connectors-2.x.0-bin`
contains all io connect nars
+
+Inspect the artifacts:
+* Check that the `LICENSE` and `NOTICE` files cover all included jars for the
-bin package)
+ - Use script to cross-validate `LICENSE` file with included jars:
+ ```
+ src/check-binary-license
distribution/server/target/apache-pulsar-2.x.0-bin.tar.gz
+ ```
+* Unpack src package: `target/apache-pulsar-2.X.0-src.tar.gz`
+ - Run Apache RAT to verify the license headers in the `src` package:
+ ```shell
+ cd apache-pulsar-2.X.0
+ mvn apache-rat:check
+ ```
+* Unpack bin package:
`distribution/server/target/apache-pulsar-2.X.0-bin.tar.gz`, Check that the
standalone Pulsar service starts correctly:
+ ```shell
+ cd apache-pulsar-2.X.0
+ cp -r ../../../io/target/apache-pulsar-io-connectors-2.X.0-bin connectors
+ bin/pulsar standalone
+ ```
+
+* Use instructions in
[Release-Candidate-Validation](https://github.com/apache/pulsar/blob/master/wiki/release/release-candidate-validation.md)
to do some sanity checks on the produced binary distributions.
+
+### Build RPM and DEB packages
+
+```shell
+pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
+
+pulsar-client-cpp/pkg/deb/docker-build-deb.sh
+```
+
+> For 2.11.0 or higher, you can set the environment variable `BUILD_IMAGE` to
build the base image locally instead of pulling from the DockerHub.
+> Since only a few members have the permission to push the image to DockerHub,
the image might not be the latest, if you failed to build the RPM and DEB
packages, you can run `export BUILD_IMAGE=1` before running these commands.
+
+This will leave the RPM/YUM and DEB repo files in
`pulsar-client-cpp/pkg/rpm/RPMS/x86_64` and
+`pulsar-client-cpp/pkg/deb/BUILD/DEB` directory.
+
+> **NOTE**: If you get error `c++: internal compiler error: Killed (program
cc1plus)` when run `pulsar-client-cpp/pkg/deb/docker-build-deb.sh`. You may
need to expand your docker memory greater than 2GB.
+
+## Sign and stage the artifacts
+
+The `src` and `bin` artifacts need to be signed and uploaded to the dist SVN
+repository for staging.
+
+Before running the script, make sure that the `[email protected]` code signing
key is the default gpg signing key.
+One way to ensure this is to create/edit file `~/.gnupg/gpg.conf` and add a
line
+```
+default-key <key fingerprint>
+```
+where `<key fingerprint>` should be replaced with the private key fingerprint
for the `[email protected]` key. The key fingerprint can be found in `gpg -K`
output.
+
+```shell
+svn co https://dist.apache.org/repos/dist/dev/pulsar pulsar-dist-dev
+cd pulsar-dist-dev
+
+# '-candidate-1' needs to be incremented in case of multiple iteration in
getting
+# to the final release)
+svn mkdir pulsar-2.X.0-candidate-1
+
+cd pulsar-2.X.0-candidate-1
+$PULSAR_PATH/src/stage-release.sh .
+
+svn add *
+svn ci -m 'Staging artifacts and signature for Pulsar release 2.X.0'
+```
+
+## Stage artifacts in maven
+
+Upload the artifacts to ASF Nexus:
+
+```shell
+# remove CPP client binaries (they would file the license/RAT check in
"deploy")
+cd pulsar-client-cpp
+git clean -xfd
+cd ..
+
+export APACHE_USER=$USER
+export APACHE_PASSWORD=$MY_PASSWORD
+export GPG_TTY=$(tty)
+# src/settings.xml from master branch to /tmp/mvn-apache-settings.xml since
it's missing in some branches
+curl -s -o /tmp/mvn-apache-settings.xml
https://raw.githubusercontent.com/apache/pulsar/master/src/settings.xml
+# publish artifacts
+mvn deploy -DskipTests -Papache-release --settings /tmp/mvn-apache-settings.xml
+# publish org.apache.pulsar.tests:integration and it's parent pom
org.apache.pulsar.tests:tests-parent
+mvn deploy -DskipTests -Papache-release --settings
/tmp/mvn-apache-settings.xml -f tests/pom.xml -pl
org.apache.pulsar.tests:tests-parent,org.apache.pulsar.tests:integration
+```
+
+> **NOTE**: The `GPG_TTY` environment variable must be set for all the
following steps. Otherwise, some operations might fail by `gpg failed to sign
the data`.
+
+This will ask for the GPG key passphrase and then upload it to the staging
repository.
+
+> If you have deployed before, re-deploying might fail on
pulsar-presto-connector-original.
+>
+> See https://github.com/apache/pulsar/issues/17047.
+>
+> You can run `mvn clean deploy` instead of `mvn deploy` as a workaround.
+
+Log in to the ASF Nexus repository at https://repository.apache.org
+
+Click on "Staging Repositories" on the left sidebar and then select the current
+Pulsar staging repo. This should be called something like
`orgapachepulsar-XYZ`.
+
+Use the "Close" button to close the repository. This operation will take few
+minutes. Once complete click "Refresh" and now a link to the staging repository
+should be available, something like
+https://repository.apache.org/content/repositories/orgapachepulsar-XYZ
+
+## Publish release candidate docker images
+
+Run the following commands:
+
+```shell
+cd $PULSAR_HOME/docker
+./build.sh
+DOCKER_USER=<your-username> DOCKER_PASSWORD=<your-password>
DOCKER_ORG=<your-username> ./publish.sh
+```
+
+After that, the following images will be built and pushed to your own
DockerHub account.
+- pulsar
+- pulsar-all
+- pulsar-grafana
+- pulsar-standalone
+
+
+## Run the vote
+
+Send an email to the Pulsar Dev mailing list:
+
+```
+To: [email protected]
+Subject: [VOTE] Pulsar Release 2.X.0 Candidate 1
+
+This is the first release candidate for Apache Pulsar, version 2.X.0.
+
+It fixes the following issues:
+https://github.com/apache/pulsar/milestone/8?closed=1
+
+*** Please download, test and vote on this release. This vote will stay open
+for at least 72 hours ***
+
+Note that we are voting upon the source (tag), binaries are provided for
+convenience.
+
+Source and binary files:
+https://dist.apache.org/repos/dist/dev/pulsar/pulsar-2.X.0-candidate-1/
+
+SHA-512 checksums:
+028313cbbb24c5647e85a6df58a48d3c560aacc9
apache-pulsar-2.X.0-SNAPSHOT-bin.tar.gz
+f7cc55137281d5257e3c8127e1bc7016408834b1
apache-pulsar-2.x.0-SNAPSHOT-src.tar.gz
+
+Maven staging repo:
+https://repository.apache.org/content/repositories/orgapachepulsar-169/
+
+The tag to be voted upon:
+v2.X.0-candidate-1 (21f4a4cffefaa9391b79d79a7849da9c539af834)
+https://github.com/apache/pulsar/releases/tag/v2.X.0-candidate-1
+
+Pulsar's KEYS file containing PGP keys you use to sign the release:
+https://dist.apache.org/repos/dist/dev/pulsar/KEYS
+
+Docker images:
+
+<link of the pulsar images>
+
+<link of the pulsar-all image>
+
+Please download the source package, and follow the README to build
+and run the Pulsar standalone service.
+```
+
+The vote should be open for at least 72 hours (3 days). Votes from Pulsar PMC
members
+will be considered binding, while anyone else is encouraged to verify the
release and
+vote as well.
+
+If the release is approved here, you can then proceed to the next step.
Otherwise, you should repeat the previous steps and prepare another candidate
release to vote.
+
+## Move master branch to next version
+
+> **NOTE**: This step is for major releases only.
+
+You need to move the master version to the next iteration `Y` (`X + 1`).
+
+```shell
+git checkout master
+./src/set-project-version.sh 2.Y.0-SNAPSHOT
+
+git commit -m 'Bumped version to 2.Y.0-SNAPSHOT' -a
+```
+
+Since this needs to be merged into `master`, you need to follow the regular
process
+and create a Pull Request on GitHub.
+
+## Promote the release
+
+Create the final git tag:
+
+```shell
+git tag -u [email protected] v2.X.0 -m 'Release v2.X.0'
+git push origin v2.X.0
+```
+
+Promote the artifacts on the release location(repo
https://dist.apache.org/repos/dist/release limited to PMC, You may need a PMC
member's help if you are not one):
+```shell
+svn move -m "Release Apache Pulsar 2.X.Y"
https://dist.apache.org/repos/dist/dev/pulsar/pulsar-2.X.0-candidate-1 \
+ https://dist.apache.org/repos/dist/release/pulsar/pulsar-2.X.0
+```
+
+Promote the Maven staging repository for release. Login to
`https://repository.apache.org` and
+select the staging repository associated with the RC candidate that was
approved. The naming
+will be like `orgapachepulsar-XYZ`. Select the repository and click on
"Release". Artifacts
+will now be made available on Maven central.
+
+## Publish Docker Images
+
+Copy the approved candidate docker images from your personal account to
apachepulsar org.
+
+```bash
+PULSAR_VERSION=2.x.x
+OTHER_DOCKER_USER=otheruser
+for image in pulsar pulsar-all pulsar-grafana pulsar-standalone; do
+ docker pull "${OTHER_DOCKER_USER}/$image:${PULSAR_VERSION}" && {
+ docker tag "${OTHER_DOCKER_USER}/$image:${PULSAR_VERSION}"
"apachepulsar/$image:${PULSAR_VERSION}"
+ echo "Pushing apachepulsar/$image:${PULSAR_VERSION}"
+ docker push "apachepulsar/$image:${PULSAR_VERSION}"
+ }
+done
+```
+
+If you don't have the permission, you can ask someone with access to
apachepulsar org to do that.
+
+## Release Helm Chart
+
+**This step can be skipped if the major version number is not the latest.**
+
+1. Bump the image version in the Helm Chart:
[charts/pulsar/values.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/values.yaml)
+
+2. Bump the chart version and `appVersion` in the Helm Chart to the released
version:
[charts/pulsar/Chart.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/Chart.yaml)
+
+3. Send a pull request for reviews and get it merged.
+
+4. Once it is merged, the chart will be automatically released to Github
releases at https://github.com/apache/pulsar-helm-chart and updated to
https://pulsar.apache.org/charts.
+
+## Publish Python Clients
+
+:::note
+
+1. You need to create an account on PyPI: https://pypi.org/account/register/
+2. Ask anyone that has been a release manager before to add you as a
maintainer for pulsar-docker on PyPI
+3. Once you have completed the following steps in this section, you can check
if the wheels are uploaded successfully in [Download
files](https://pypi.org/project/pulsar-client/#files). Remember to switch to
the correct version in [Release
history](https://pypi.org/project/pulsar-client/#history)).
+
+:::
+
+### Linux
+
+There is a script that builds and packages the Python client inside Docker
images.
+
+> Make sure you run following command at the release tag!
+
+```shell
+pulsar-client-cpp/docker/build-wheels.sh
+```
+
+The wheel files will be left under `pulsar-client-cpp/python/wheelhouse`. Make
sure all the files have `manylinux` in the filenames. Otherwise, those files
will not be able to upload to PyPI.
+
+Run the following command to push the built wheel files.
+
+```shell
+cd pulsar-client-cpp/python/wheelhouse
+pip install twine
+twine upload pulsar_client-*.whl
+```
+
+### MacOS
+
+There is a script that builds and packages the Python client inside Docker
images.
+
+```shell
+pulsar-client-cpp/python/build-mac-wheels.sh
+```
+
+The wheel files will be generated at each platform directory under
`pulsar-client-cpp/python/pkg/osx/`.
+Then you can run `twin upload` to upload those wheel files.
+
+## Update Python Client docs
+
+After publishing the python client docs, run the following script from the
apache/pulsar-site `main` branch:
+
+```shell
+PULSAR_VERSION=2.X.Y ./site2/tools/api/python/build-docs-in-docker.sh
+```
+
+Note that it builds the docs within a docker image, so you'll need to have
docker running.
+
+Once the docs are generated, you can add them and submit them in a PR. The
expected doc output is `site2/website/static/api/python`.
+
+## Publish Homebrew libpulsar package
+
+**This step can be skipped if the major version number is not the latest.**
+
+Release a new version of libpulsar for Homebrew, You can follow the example
[here](https://github.com/Homebrew/homebrew-core/pull/53514).
+
+## Update swagger file
+
+> For major releases, the swagger file update happen under `master` branch.
+> while for minor releases, swagger file is created from branch-2.x, and need
copy to a new branch based on master.
+
+```shell
+git checkout branch-2.X
+mvn -am -pl pulsar-broker install -DskipTests -Pswagger
+git checkout master
+git checkout -b fix/swagger-file
+mkdir -p site2/website/static/swagger/2.X.0
+cp pulsar-broker/target/docs/*.json site2/website/static/swagger/2.X.0
+```
+Send out a PR request for review.
+
+## Write release notes
+
+See [Pulsar Release Notes Guide](./release-note-guide.md).
+
+## Update the site
+
+:::note
+
+This step is for major releases only.
+
+:::
+
+For major releases, such as 2.10.0, the website is updated based on the
`master` branch.
+
+1. Create a new branch off master.
+
+```shell
+git checkout -b doc_release_<release-version>
+```
+
+2. Go to the website directory.
+
+```shell
+cd site2/website
+```
+
+3. Generate a new version of the documentation.
+
+```shell
+yarn install
+yarn run version <release-version>
+```
+
+After you run this command, a new folder `version-<release-version>` is added
in the `site2/website/versioned_docs` directory, a new sidebar file
`version-<release-version>-sidebars.json` is added in the
`site2/website/versioned_sidebars` directory, and the new version is added in
the `versions.json` file, shown as follows:
+
+```shell
+versioned_docs/version-<release-version>
+versioned_sidebars/version-<release-version>-sidebars.json
+```
+
+:::note
+
+You can move the latest version under the old version in the `versions.json`
file. Make sure the Algolia index works before moving 2.X.0 as the current
stable.
+
+:::
+
+4. Update the `releases.json` file by adding `<release-version>` to the second
of the list (this is to make the search work. After your PR is merged, the
Pulsar website is built and tagged for search, you can change it to the first
list).
+
+5. Send out a PR request for review.
+
+ After your PR is approved and merged to master, the website is published
automatically after the new website is built. The website is built every 6
hours.
+
+6. Check the new website after the website is built. Open
https://pulsar.apache.org in your browsers to verify all the changes are alive.
If the website build succeeds but the website is not updated, you can try to
sync the git repository. Navigate to https://selfserve.apache.org/ and click
the "Synchronize Git Repositories" and then select apache/pulsar.
+
+7. Publish the release on GitHub, and copy the same release notes:
https://github.com/apache/pulsar/releases.
+
+8. Update the deploy version to the current release version in
`deployment/terraform-ansible/deploy-pulsar.yaml`.
+
+9. Generate the doc set and sidebar file for the next major release `2.X.x`
based on the `site2/docs` folder. You can follow steps 1, 2, and 3, and submit
those files to the `apache/pulsar` repository. This step is a preparation for
the `2.X.x` release.
+
+:::note
+
+Starting from 2.8.0, you don't need to generate an independent doc set or
update the Pulsar site for minor releases, such as 2.8.1, 2.8.2, and so on.
Instead, the generic doc set 2.8.x is used.
+
+:::note
+
+## Announce the release
+
+Once the release artifacts are available in the Apache Mirrors and the website
is updated,
+we need to announce the release.
+
+Send an email to these lines:
+
+```
+To: [email protected], [email protected], [email protected]
+Subject: [ANNOUNCE] Apache Pulsar 2.X.0 released
+
+The Apache Pulsar team is proud to announce Apache Pulsar version 2.X.0.
+
+Pulsar is a highly scalable, low latency messaging platform running on
+commodity hardware. It provides simple pub-sub semantics over topics,
+guaranteed at-least-once delivery of messages, automatic cursor management for
+subscribers, and cross-datacenter replication.
+
+For Pulsar release details and downloads, visit:
+
+https://pulsar.apache.org/download
+
+Release Notes are at:
+https://pulsar.apache.org/release-notes
+
+We would like to thank the contributors that made the release possible.
+
+Regards,
+
+The Pulsar Team
+```
+
+Send the email in plain text mode since the [email protected] mailing list
will reject messages with text/html content.
+In Gmail, there's an option to set `Plain text mode` in the `⋮`/ `More
options` menu.
+
+
+## Write a blog post for the release (optional)
+
+It is encouraged to write a blog post to summarize the features introduced in
this release,
+especially for feature releases.
+You can follow the example [here](https://github.com/apache/pulsar/pull/2308)
+
+## Remove old releases
+
+Remove the old releases (if any). You only need the latest release there, and
older releases are
+available through the Apache archive:
+
+```shell
+# Get the list of releases
+svn ls https://dist.apache.org/repos/dist/release/pulsar
+
+# Delete each release (except for the last one)
+svn rm https://dist.apache.org/repos/dist/release/pulsar/pulsar-2.Y.0
+```
+
+## Move release branch to next version
+
+Run the following commands in the release branches.
+
+```shell
+./src/set-project-version.sh 2.X.Y-SNAPSHOT
+
+git commit -m 'Bumped version to 2.X.Y-SNAPSHOT' -a
+git push origin branch-2.X
+```
diff --git
a/site2/website-next/contribute/releasing/validate-release-candidate.md
b/site2/website-next/contribute/releasing/validate-release-candidate.md
new file mode 100644
index 00000000000..962f5e6624d
--- /dev/null
+++ b/site2/website-next/contribute/releasing/validate-release-candidate.md
@@ -0,0 +1,630 @@
+---
+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.
+
+## Validate the binary distribution
+
+### Download And Verify the binary distributions
+
+Download the server distribution `apache-pulsar-<release>-bin.tar.gz` and
extract it. The extracted files are in a directory called
`apache-pulsar-<release>`. All the operations below happen within that
directory:
+
+```shell
+cd apache-pulsar-<release>
+mkdir connectors
+```
+
+Download the Pulsar IO Connector files:
+
+```
+pulsar-io-aerospike-<release>.nar
+pulsar-io-cassandra-<release>.nar
+pulsar-io-kafka-<release>.nar
+pulsar-io-kinesis-<release>.nar
+pulsar-io-rabbitmq-<release>.nar
+pulsar-io-twitter-<release>.nar
+```
+
+and place them in the `connectors` directory.
+
+Download the `*.asc` file and verify the GPG signature:
+
+```bash
+gpg verify apache-pulsar-<release>-bin.tar.gz.asc
+```
+
+### Validate Pub/Sub and Java Functions
+
+#### Standalone service
+
+Open a terminal to start a standalone service:
+
+```shell
+bin/pulsar standalone
+```
+
+When you start a standalone cluster, there are a few things to check.
+
+1. The standalone cluster is able to locate all the connectors. The following
logging information should be displayed.
+
+```text
+Found connector ConnectorDefinition(name=kinesis, description=Kinesis sink
connector, sourceClass=null,
sinkClass=org.apache.pulsar.io.kinesis.KinesisSink) from
/Users/sijie/tmp/apache-pulsar-2.1.0-incubating/./connectors/pulsar-io-kinesis-2.1.0-incubating.nar
+...
+Found connector ConnectorDefinition(name=cassandra, description=Writes data
into Cassandra, sourceClass=null,
sinkClass=org.apache.pulsar.io.cassandra.CassandraStringSink) from
/Users/sijie/tmp/apache-pulsar-2.1.0-incubating/./connectors/pulsar-io-cassandra-2.1.0-incubating.nar
+...
+Found connector ConnectorDefinition(name=aerospike, description=Aerospike
database sink, sourceClass=null,
sinkClass=org.apache.pulsar.io.aerospike.AerospikeStringSink) from
/Users/sijie/tmp/apache-pulsar-2.1.0-incubating/./connectors/pulsar-io-aerospike-2.1.0-incubating.nar
+```
+
+2. (since Pulsar 2.1 release) The standalone starts bookkeeper table service.
The output is similar as follows:
+
+```text
+12:12:26.099 [main] INFO org.apache.pulsar.zookeeper.LocalBookkeeperEnsemble
- 'default' namespace for table service : namespace_name: "default"
+default_stream_conf {
+ key_type: HASH
+ min_num_ranges: 24
+ initial_num_ranges: 24
+ split_policy {
+ fixed_range_policy {
+ num_ranges: 2
+ }
+ }
+ rolling_policy {
+ size_policy {
+ max_segment_size: 134217728
+ }
+ }
+ retention_policy {
+ time_policy {
+ retention_minutes: -1
+ }
+ }
+}
+```
+
+3. Functions worker is started correctly. The output is similar as follows:
+
+```text
+14:28:24.101 [main] INFO org.apache.pulsar.functions.worker.WorkerService -
Starting worker c-standalone-fw-localhost-8080...
+14:28:24.907 [main] INFO org.apache.pulsar.functions.worker.WorkerService -
Worker Configs: {
+ "workerId" : "c-standalone-fw-localhost-8080",
+ "workerHostname" : "localhost",
+ "workerPort" : 8080,
+ "workerPortTls" : 6751,
+ "jvmGCMetricsLoggerClassName" : null,
+ "numHttpServerThreads" : 8,
+ "connectorsDirectory" : "./connectors",
+ "functionMetadataTopicName" : "metadata",
+ "functionWebServiceUrl" : null,
+ "pulsarServiceUrl" : "pulsar://127.0.0.1:6650",
+ "pulsarWebServiceUrl" : "http://127.0.0.1:8080";,
+ "clusterCoordinationTopicName" : "coordinate",
+ "pulsarFunctionsNamespace" : "public/functions",
+ "pulsarFunctionsCluster" : "standalone",
+ "numFunctionPackageReplicas" : 1,
+ "downloadDirectory" : "/tmp/pulsar_functions",
+ "stateStorageServiceUrl" : "bk://127.0.0.1:4181",
+ "functionAssignmentTopicName" : "assignments",
+ "schedulerClassName" :
"org.apache.pulsar.functions.worker.scheduler.RoundRobinScheduler",
+ "failureCheckFreqMs" : 30000,
+ "rescheduleTimeoutMs" : 60000,
+ "initialBrokerReconnectMaxRetries" : 60,
+ "assignmentWriteMaxRetries" : 60,
+ "instanceLivenessCheckFreqMs" : 30000,
+ "clientAuthenticationPlugin" : null,
+ "clientAuthenticationParameters" : null,
+ "topicCompactionFrequencySec" : 1800,
+ "tlsEnabled" : true,
+ "tlsCertificateFilePath" : null,
+ "tlsKeyFilePath" : null,
+ "tlsTrustCertsFilePath" : null,
+ "tlsAllowInsecureConnection" : false,
+ "tlsRequireTrustedClientCertOnConnect" : false,
+ "useTls" : false,
+ "tlsHostnameVerificationEnable" : false,
+ "authenticationEnabled" : false,
+ "authenticationProviders" : null,
+ "authorizationEnabled" : false,
+ "superUserRoles" : null,
+ "properties" : { },
+ "threadContainerFactory" : null,
+ "processContainerFactory" : {
+ "javaInstanceJarLocation" : null,
+ "pythonInstanceLocation" : null,
+ "logDirectory" : null,
+ "extraFunctionDependenciesDir" : null
+ },
+ "kubernetesContainerFactory" : null,
+ "secretsProviderConfiguratorClassName" : null,
+ "secretsProviderConfiguratorConfig" : null,
+ "functionInstanceMinResources" : null,
+ "workerWebAddress" : "http://localhost:8080";,
+ "functionMetadataTopic" : "persistent://public/functions/metadata",
+ "clusterCoordinationTopic" : "persistent://public/functions/coordinate",
+ "functionAssignmentTopic" : "persistent://public/functions/assignments"
+}
+```
+
+4. Do sanity check before moving to the next step.
+
+```shell
+# check pulsar binary port is listened correctly
+netstat -an | grep 6650 | grep LISTEN
+
+# check function cluster
+curl -s http://localhost:8080/admin/v2/worker/cluster
+# example output:
+#
[{"workerId":"c-standalone-fw-localhost-6750","workerHostname":"localhost","port":6750}]
+
+# check brokers
+curl -s http://localhost:8080/admin/v2/namespaces/public
+# example outoupt:
+# ["public/default","public/functions"]
+
+# check connectors
+curl -s http://localhost:8080/admin/v2/functions/connectors
+# example output:
+# [{"name":"aerospike","description":"Aerospike database
sink","sinkClass":"org.apache.pulsar.io.aerospike.AerospikeStringSink"},{"name":"cassandra","description":"Writes
data into
Cassandra","sinkClass":"org.apache.pulsar.io.cassandra.CassandraStringSink"},{"name":"kafka","description":"Kafka
source and sink
connector","sourceClass":"org.apache.pulsar.io.kafka.KafkaStringSource","sinkClass":"org.apache.pulsar.io.kafka.KafkaStringSink"},{"name":"kinesis","description":"Kinesis
sink conne [...]
+
+# check table services
+nc -vz4 localhost 4181
+```
+
+#### Functions
+
+Open another terminal to submit a Java Exclamation function.
+
+1. Create tenant and namespace:
+
+```shell
+bin/pulsar-admin tenants create test
+bin/pulsar-admin namespaces create test/test-namespace
+```
+
+2. Create function.
+
+```shell
+bin/pulsar-admin functions create --function-config-file
examples/example-function-config.yaml --jar examples/api-examples.jar
+```
+
+The following information is returned: `Created Successfully`.
+
+3. At the same terminal as step 2, retrieve the function configuration.
+
+```shell
+bin/pulsar-admin functions get --tenant test --namespace test-namespace --name
example
+```
+
+The output is similar as follows:
+
+```json
+{
+ "tenant": "test",
+ "namespace": "test-namespace",
+ "name": "example",
+ "className": "org.apache.pulsar.functions.api.examples.ExclamationFunction",
+ "userConfig": "{\"PublishTopic\":\"test_result\"}",
+ "autoAck": true,
+ "parallelism": 1,
+ "source": {
+ "topicsToSerDeClassName": {
+ "test_src": ""
+ },
+ "typeClassName": "java.lang.String"
+ },
+ "sink": {
+ "topic": "test_result",
+ "typeClassName": "java.lang.String"
+ },
+ "resources": {}
+}
+```
+
+4. At the same terminal as step 3, retrieve the function status.
+
+```shell
+bin/pulsar-admin functions status --tenant test --namespace test-namespace
--name example
+```
+
+The output is similar as follows:
+
+```json
+{
+ "numInstances" : 1,
+ "numRunning" : 1,
+ "instances" : [ {
+ "instanceId" : 0,
+ "status" : {
+ "running" : true,
+ "error" : "",
+ "numRestarts" : 0,
+ "numReceived" : 0,
+ "numSuccessfullyProcessed" : 0,
+ "numUserExceptions" : 0,
+ "latestUserExceptions" : [ ],
+ "numSystemExceptions" : 0,
+ "latestSystemExceptions" : [ ],
+ "averageLatency" : 0.0,
+ "lastInvocationTime" : 0,
+ "workerId" : "c-standalone-fw-localhost-8080"
+ }
+ } ]
+}
+```
+
+5. At the same terminal as step 4, subscribe the output topic `test_result`.
+
+```shell
+bin/pulsar-client consume -s test-sub -n 0 test_result
+```
+
+6. Open a new terminal to produce messages into the input topic `test_src`.
+
+```shell
+bin/pulsar-client produce -m "test-messages-`date`" -n 10 test_src
+```
+
+7. At the terminal of step 5, the messages produced by the Exclamation
function is returned. The output is similar as follows:
+
+```text
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+----- got message -----
+test-messages-Thu Jul 19 11:59:15 PDT 2018!
+```
+
+### Validate Connectors
+
+:::note
+
+Make sure you have docker available at your laptop. If you haven't installed
docker, you can skip this section.
+
+:::
+
+1. Set up a cassandra cluster.
+
+```shell
+docker run -d --rm --name=cassandra -p 9042:9042 cassandra
+```
+
+Make sure that the cassandra cluster is running.
+
+```shell
+# run docker ps to find the docker process for cassandra
+docker ps
+```
+
+```shell
+# check if the cassandra is running as expected
+docker logs cassandra
+```
+
+```shell
+# check the cluster status
+docker exec cassandra nodetool status
+
+# Datacenter: datacenter1
+# =======================
+# Status=Up/Down
+# |/ State=Normal/Leaving/Joining/Moving
+# -- Address Load Tokens Owns (effective) Host ID
Rack
+# UN 172.17.0.2 103.67 KiB 256 100.0%
af0e4b2f-84e0-4f0b-bb14-bd5f9070ff26 rack1
+```
+
+2. Create keyspace and table.
+
+Run `cqlsh`:
+
+```shell
+docker exec -ti cassandra cqlsh localhost
+```
+
+In the cqlsh, create the `pulsar_test_keyspace` keyspace and the
`pulsar_test_table` table.
+
+```text
+cqlsh> CREATE KEYSPACE pulsar_test_keyspace WITH replication =
{'class':'SimpleStrategy', 'replication_factor':1};
+cqlsh> USE pulsar_test_keyspace;
+cqlsh:pulsar_test_keyspace> CREATE TABLE pulsar_test_table (key text PRIMARY
KEY, col text);
+
+```
+
+3. Prepare a cassandra sink yaml file and put it under examples directory as
`cassandra-sink.yml`.
+
+```shell
+cat examples/cassandra-sink.yml
+```
+
+The content should be:
+
+```yaml
+configs:
+ roots: "localhost:9042"
+ keyspace: "pulsar_test_keyspace"
+ columnFamily: "pulsar_test_table"
+ keyname: "key"
+ columnName: "col"
+```
+
+4. Submit a cassandra sink.
+
+```shell
+bin/pulsar-admin sink create --tenant public --namespace default --name
cassandra-test-sink --sink-type cassandra --sink-config-file
examples/cassandra-sink.yml --inputs test_cassandra
+# "Created successfully"
+```
+
+Get the sink info:
+
+```shell
+bin/pulsar-admin sink get --tenant public --namespace default --name
cassandra-test-sink
+```
+
+The output is similar as follows:
+
+```json
+{
+ "tenant": "public",
+ "namespace": "default",
+ "name": "cassandra-test-sink",
+ "className": "org.apache.pulsar.io.cassandra.CassandraStringSink",
+ "inputSpecs": {
+ "test_cassandra": {
+ "isRegexPattern": false
+ }
+ },
+ "configs": {
+ "roots": "localhost:9042",
+ "keyspace": "pulsar_test_keyspace",
+ "columnFamily": "pulsar_test_table",
+ "keyname": "key",
+ "columnName": "col"
+ },
+ "parallelism": 1,
+ "processingGuarantees": "ATLEAST_ONCE",
+ "retainOrdering": false,
+ "autoAck": true,
+ "archive": "builtin://cassandra"
+}
+```
+
+Get the running status:
+
+```shell
+bin/pulsar-admin sink status --tenant public --namespace default --name
cassandra-test-sink
+```
+
+The output is similar as follows:
+
+```json
+{
+ "numInstances" : 1,
+ "numRunning" : 1,
+ "instances" : [ {
+ "instanceId" : 0,
+ "status" : {
+ "running" : true,
+ "error" : "",
+ "numRestarts" : 0,
+ "numReadFromPulsar" : 0,
+ "numSystemExceptions" : 0,
+ "latestSystemExceptions" : [ ],
+ "numSinkExceptions" : 0,
+ "latestSinkExceptions" : [ ],
+ "numWrittenToSink" : 0,
+ "lastReceivedTime" : 0,
+ "workerId" : "c-standalone-fw-localhost-8080"
+ }
+ } ]
+}
+```
+
+5. Produce messages to the source topic.
+
+```shell
+for i in {0..10}; do bin/pulsar-client produce -m "key-$i" -n 1
test_cassandra; done
+```
+
+6. Check the sink status, and 11 messages are processed.
+
+```shell
+bin/pulsar-admin sink status --tenant public --namespace default --name
cassandra-test-sink
+```
+
+The output is similar as follows:
+
+```json
+{
+ "numInstances" : 1,
+ "numRunning" : 1,
+ "instances" : [ {
+ "instanceId" : 0,
+ "status" : {
+ "running" : true,
+ "error" : "",
+ "numRestarts" : 0,
+ "numReadFromPulsar" : 11,
+ "numSystemExceptions" : 0,
+ "latestSystemExceptions" : [ ],
+ "numSinkExceptions" : 0,
+ "latestSinkExceptions" : [ ],
+ "numWrittenToSink" : 11,
+ "lastReceivedTime" : 1554833501277,
+ "workerId" : "c-standalone-fw-localhost-8080"
+ }
+ } ]
+}
+```
+
+7. Check results in cassandra.
+
+```shell
+docker exec -ti cassandra cqlsh localhost
+```
+
+In the cqlsh session:
+
+```text
+cqlsh> use pulsar_test_keyspace;
+cqlsh:pulsar_test_keyspace> select * from pulsar_test_table;
+
+ key | col
+--------+--------
+ key-5 | key-5
+ key-0 | key-0
+ key-9 | key-9
+ key-2 | key-2
+ key-1 | key-1
+ key-3 | key-3
+ key-6 | key-6
+ key-7 | key-7
+ key-4 | key-4
+ key-8 | key-8
+ key-10 | key-10
+
+(11 rows)
+```
+
+8. Delete the sink.
+
+```shell
+bin/pulsar-admin sink delete --tenant public --namespace default --name
cassandra-test-sink
+# "Deleted successfully"
+```
+
+### Validate Stateful Functions
+
+Since Pulsar 2.1 release, Pulsar enables bookkeeper table service for stateful
Pulsar functions (as a developer preview).
+
+The following are instructions to validate counter functions.
+
+1. Create a wordcount function.
+
+```shell
+bin/pulsar-admin functions create --function-config-file
examples/example-function-config.yaml --jar examples/api-examples.jar --name
word_count --className
org.apache.pulsar.functions.api.examples.WordCountFunction --inputs
test_wordcount_src --output test_wordcount_dest
+# "Created successfully"
+```
+
+2. Get function information and status.
+
+```shell
+bin/pulsar-admin functions get --tenant test --namespace test-namespace --name
word_count
+```
+
+The output is similar as follows:
+
+```json
+{
+ "tenant": "test",
+ "namespace": "test-namespace",
+ "name": "word_count",
+ "className": "org.apache.pulsar.functions.api.examples.WordCountFunction",
+ "inputSpecs": {
+ "test_wordcount_src": {
+ "isRegexPattern": false
+ }
+ },
+ "output": "test_wordcount_dest",
+ "processingGuarantees": "ATLEAST_ONCE",
+ "retainOrdering": false,
+ "userConfig": {
+ "PublishTopic": "test_result"
+ },
+ "runtime": "JAVA",
+ "autoAck": true,
+ "parallelism": 1,
+ "resources": {
+ "cpu": 1.0,
+ "ram": 1073741824,
+ "disk": 10737418240
+ },
+ "cleanupSubscription": true
+}
+```
+
+```shell
+bin/pulsar-admin functions status --tenant test --namespace test-namespace
--name word_count
+```
+
+The output is similar as follows:
+
+```json
+{
+ "numInstances" : 1,
+ "numRunning" : 1,
+ "instances" : [ {
+ "instanceId" : 0,
+ "status" : {
+ "running" : true,
+ "error" : "",
+ "numRestarts" : 0,
+ "numReceived" : 0,
+ "numSuccessfullyProcessed" : 0,
+ "numUserExceptions" : 0,
+ "latestUserExceptions" : [ ],
+ "numSystemExceptions" : 0,
+ "latestSystemExceptions" : [ ],
+ "averageLatency" : 0.0,
+ "lastInvocationTime" : 0,
+ "workerId" : "c-standalone-fw-localhost-8080"
+ }
+ } ]
+}
+```
+
+3. Query the state table for the function: watching on a key called "hello"
+
+```shell
+bin/pulsar-admin functions querystate --tenant test --namespace test-namespace
--name word_count -k hello -w
+# key 'hello' doesn't exist.
+# key 'hello' doesn't exist.
+# key 'hello' doesn't exist
+```
+
+4. Produce the messages to source topic `test_wordcount_src`.
+
+Produce 10 messages "hello" to the `test_wordcount_src` topic. The value of
"hello" is updated to 10.
+
+```shell
+bin/pulsar-client produce -m "hello" -n 10 test_wordcount_src
+```
+
+Checkout the result in the terminal of step 3.
+
+```json
+{
+ "key": "hello",
+ "numberValue": 10,
+ "version": 9
+}
+```
+
+Produce another 10 messages "hello". The result is updated to 20.
+
+```json
+bin/pulsar-client produce -m "hello" -n 10 test_wordcount_src
+```
+
+The result in the terminal of step 3 is updated to `20`.
+
+```text
+ "key": "hello",
+ "numberValue": 20,
+ "version": 19
+```
diff --git a/site2/website-next/contribute/testing-and-ci/_category_.json
b/site2/website-next/contribute/testing-and-ci/_category_.json
new file mode 100644
index 00000000000..c1473a070f8
--- /dev/null
+++ b/site2/website-next/contribute/testing-and-ci/_category_.json
@@ -0,0 +1,7 @@
+{
+ "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
new file mode 100644
index 00000000000..243b9d6cd59
--- /dev/null
+++ b/site2/website-next/contribute/testing-and-ci/ci-testing-in-fork.md
@@ -0,0 +1,63 @@
+---
+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-and-ci/licensing.md
new file mode 100644
index 00000000000..6c30cddd37a
--- /dev/null
+++ b/site2/website-next/contribute/testing-and-ci/licensing.md
@@ -0,0 +1,11 @@
+---
+id: licensing
+title: Licensing
+sidebar_label: "Licensing"
+---
+
+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:
+
+```bash
+mvn initialize license:format
+```
diff --git a/site2/website-next/docusaurus.config.js
b/site2/website-next/docusaurus.config.js
index 2a4b4c2ed47..f59f76de754 100644
--- a/site2/website-next/docusaurus.config.js
+++ b/site2/website-next/docusaurus.config.js
@@ -181,6 +181,11 @@ module.exports = {
position: "right",
label: "Docs",
},
+ {
+ href: "/contribute/",
+ position: "right",
+ label: "Contribute",
+ },
{
type: "dropdown",
label: "Community",
@@ -400,6 +405,18 @@ module.exports = {
// }),
// ],
"./postcss-tailwind-loader",
+ [
+ '@docusaurus/plugin-content-docs',
+ {
+ id: 'contribute',
+ path: 'contribute',
+ routeBasePath: 'contribute',
+ showLastUpdateAuthor: true,
+ showLastUpdateTime: true,
+ sidebarPath: require.resolve('./sidebarsContribute.js'),
+ editUrl:
'https://github.com/apache/pulsar-site/tree/main/site2/website-next',
+ },
+ ],
[
"content-docs",
/** @type {import('@docusaurus/plugin-content-docs').Options} */
diff --git a/site2/website-next/sidebarsContribute.js
b/site2/website-next/sidebarsContribute.js
new file mode 100644
index 00000000000..4f4bda0ac35
--- /dev/null
+++ b/site2/website-next/sidebarsContribute.js
@@ -0,0 +1,6 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+ sidebar: [{type: 'autogenerated', dirName: '.'}],
+};
+
+module.exports = sidebars;
diff --git a/site2/website-next/src/pages/coding-guide.md
b/site2/website-next/src/pages/coding-guide.md
index fbee816d8a9..59b14fbac01 100644
--- a/site2/website-next/src/pages/coding-guide.md
+++ b/site2/website-next/src/pages/coding-guide.md
@@ -17,7 +17,7 @@ Apache Pulsar code follows the [Sun Java Coding
Convention](http://www.oracle.co
* Use curly braces even for single-line ifs and elses.
* No @author tags in any javadoc.
* Use try-with-resources blocks whenever is possible.
-* **TODO**s should be associated to at least one issue.
+* **TODO**s should be associated to at least one issue.
## Dependencies
@@ -26,7 +26,7 @@ Apache Pulsar uses the following libraries a lot:
* [Guava](https://github.com/google/guava): as a fundamental core library
* [Netty](http://netty.io/): for network communications and memory buffer
management.
-Use these libraries whenever possible rather than introducing more
dependencies.
+Use these libraries whenever possible rather than introducing more
dependencies.
Dependencies are bundled with our binary distributions, so we need to attach
the relevant licenses. See [Third party dependencies and
licensing](https://pulsar.apache.org/docs/en/client-libraries/) for a guide on
how to do it correctly.
diff --git a/site2/website-next/src/pages/contributing.md
b/site2/website-next/src/pages/contributing.md
index f2e4dd11b1c..3021c02fd76 100644
--- a/site2/website-next/src/pages/contributing.md
+++ b/site2/website-next/src/pages/contributing.md
@@ -22,9 +22,9 @@ We use a review-then-commit workflow in Pulsar for all
contributions.
**For all contributions:**
-1. **Code:** code changes are always welcomed.
-2. **Doc**: it is worth taking the time to make users know your code changes.
Pulsar's long-term success rests on its ease of use, maintainability, etc.
-
+1. **Code:** code changes are always welcomed.
+2. **Doc**: it is worth taking the time to make users know your code changes.
Pulsar's long-term success rests on its ease of use, maintainability, etc.
+
:::tip
For how to make contributions to Pulsar documentation, see [Pulsar
Documentation Contribution
Guide](https://docs.google.com/document/d/11DTnNPpvcPrebLkMAFcDEIFlD8ARD-k6F-LXoIwdD9Y/edit#).
@@ -135,7 +135,7 @@ You are now ready to start developing!
#### IDE Setup
-For how to set up IDE, see
[here](https://github.com/apache/pulsar/blob/master/README.md#setting-up-your-ide).
+For how to set up IDE, see
[here](https://github.com/apache/pulsar/blob/master/README.md#setting-up-your-ide).
### Create a branch in your fork
@@ -302,7 +302,7 @@ You'll then push to your branch on GitHub. Note: when
updating your commit after
Navigate to the [Pulsar GitHub Repo](https://github.com/apache/pulsar) to
create a pull request.
> **Note**
->
+>
> Vague, boring, and unclear PR titles decrease team efficiency and
> productivity. Good titles speed up the review process and increase search
> efficiency. PR titles should be engaging, easy to understand, and readable.
> For how to **write self-explanatory PR titles** and **quality PR title
> examples**, see [[Guideline] Pulsar PR Naming
> Convention](https://docs.google.com/document/d/1d8Pw6ZbWk-_pCKdOmdvx9rnhPiyuxwq60_TrD68d7BA/edit#).
In the pull request description, please include:
@@ -358,9 +358,9 @@ Once the code has been peer reviewed by a committer, the
next step is for the co
Pull requests should not be merged before the review has approved from at
least 2 committers.
> **Tip**
->
+>
> Git commit message is not only the best way to communicate context about
> code changes, but also shows whether a developer is a good collaborator. If
> the first commit message of a PR is not clear but the PR description is
> clear and concise, when merging a PR, consider copying the PR description to
> the commit message box or writing a proper one rather than using the default
> (first) commit message (see image below). In this way, others know the
> changes clearly, which is beneficial to cut [...]
-
+
### Contributor License Agreement
@@ -383,7 +383,7 @@ The Apache Pulsar Community welcomes all users to update
their company logos on
To update your company's logo, follow these steps:
1. Open
[link](https://github.com/apache/pulsar-site/tree/main/site2/website-next/data/users.js)
in your browser, then click the **Edit** icon to fork Pulsar repo, create a
new branch and edit this file.
-2. Add your company’s information at the end of file.
+2. Add your company’s information at the end of file.
Example:
```
diff --git a/site2/website-next/src/pages/markdown-page.md
b/site2/website-next/src/pages/markdown-page.md
deleted file mode 100644
index 9756c5b6685..00000000000
--- a/site2/website-next/src/pages/markdown-page.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: Markdown page example
----
-
-# Markdown page example
-
-You don't need React to write simple standalone pages.
