You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/10/17 10:59:03 UTC

[GitHub] [pulsar] Anonymitaet opened a new pull request, #18071: [feat][doc] Add various doc contribution guides

Anonymitaet opened a new pull request, #18071:
URL: https://github.com/apache/pulsar/pull/18071

   1. This PR adds the doc contribution guides in green circles. They were reviewed in [google docs](https://docs.google.com/document/d/11DTnNPpvcPrebLkMAFcDEIFlD8ARD-k6F-LXoIwdD9Y/edit#heading=h.wl1ajmlh0thj) previously. 
   
   <img width="618" alt="image" src="https://user-images.githubusercontent.com/50226895/196160283-2af29157-c0ca-4777-ac03-1ba27de64f03.png">
   
   2. I'll add the rest guides (once I finish) to the Pulsar repo in the future.
   - [x] `doc`


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] Anonymitaet merged pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
Anonymitaet merged PR #18071:
URL: https://github.com/apache/pulsar/pull/18071


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] momo-jun commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
momo-jun commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997726843


##########
site2/doc-guides/label.md:
##########
@@ -0,0 +1,19 @@
+# Pulsar Documentation Label Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide instructs you on how to label your doc PR.
+
+When submitting an issue or PR, you must [provide doc label information](https://github.com/apache/pulsar/blob/master/.github/PULL_REQUEST_TEMPLATE.md#documentation) by **selecting the checkbox**, so that the Bot can label the PR correctly. 
+
+Label name|Usage
+|---|---
+`doc-required`|Use this label to indicate this issue or PR impacts documentation.<br><br> **You have not updated the docs yet**. The docs will be submitted later. 
+`doc-not-needed`| The code changes in this PR do not impact documentation.
+`doc`|This PR contains changes that impact documentation, **no matter whether the changes are in markdown or code files**.
+`doc-complete`|Use this label to indicate the documentation updates are complete.
+`doc-label-missing`|The Bot applies this label when there is no doc label information in the PR if one of the following conditions is met:. <br><br> - You do not provide a doc label. <br><br> - You provide multiple doc labels. <br><br> - You delete backticks (``) in doc labels. <br>For example,<br> [x] `doc-required` βœ… <br> [x] doc-required ❌ <br><br> - You add blanks in square brackets. <br>For example, <br> [x] `doc-required` βœ… <br>[ x ] `doc-required` ❌

Review Comment:
   What I thought is to keep the colon but remove the extra comma:)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] Anonymitaet commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997019315


##########
site2/doc-guides/contribution.md:
##########
@@ -0,0 +1,219 @@
+# Pulsar Documentation Contribution Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains the organization of Pulsar documentation and website repos and the workflow of updating various Pulsar docs.
+
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Contribution Guide](#pulsar-documentation-contribution-guide)
+  - [Documentation and website repos](#documentation-and-website-repos)
+    - [Intro to doc and website repos](#intro-to-doc-and-website-repos)
+    - [Relationships between doc and website repos](#relationships-between-doc-and-website-repos)
+  - [Update versioned docs](#update-versioned-docs)
+  - [Update reference docs](#update-reference-docs)
+    - [Update Pulsar configuration docs](#update-pulsar-configuration-docs)
+    - [Update client configuration docs](#update-client-configuration-docs)
+    - [Update CLI tool docs](#update-cli-tool-docs)
+  - [Update client/function matrix](#update-clientfunction-matrix)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Documentation and website repos
+
+This chapter shows the organization of Pulsar documentation and website repos
+
+### Intro to doc and website repos
+
+The Pulsar website consists of two parts:
+
+* **Documentation**
+
+  Pulsar documentation repo: [pulsar/site2](https://github.com/apache/pulsar/tree/master/site2)
+
+  ![alt_text](assets/contribution-1.png)
+  
+* **Website** 
+
+  Pulsar website repo: [pulsar-site](https://github.com/apache/pulsar-site)
+
+  ![alt_text](assets/contribution-2.png)
+
+### Relationships between doc and website repos
+
+Type|Repo|Description|PR example
+|---|---|---|---
+Documentation|[pulsar/site2](https://github.com/apache/pulsar/tree/master/site2)|All files related to Pulsar documentation (English) are stored in this repo.|[[feat][doc] add docs for shedding strategy](https://github.com/apache/pulsar/pull/13811)
+Website|[pulsar-site](https://github.com/apache/pulsar-site)|- All files related to the Pulsar website are stored in the **main** branch in this repo. <br><br> - The website is built and put in in the **asf-site-next** branch in this repo.|- [[feat][workflow] add links of doc contribution guides to Pulsar contribution page](https://github.com/apache/pulsar-site/pull/114) <br><br> - [[improve][website] add download links for previous versions](https://github.com/apache/pulsar-site/pull/108)
+
+Files in [pulsar/site2 (master branch)](https://github.com/apache/pulsar/tree/master/site2) are synced to [pulsar-site/website-next (main branch)](https://github.com/apache/pulsar-site/tree/main/site2/website-next) every 6 hours. You can check the sync status and progress at [pulsar-site Actions](https://github.com/apache/pulsar-site/actions/workflows/ci-pulsar-website-docs-sync.yaml).
+
+> **Summary**
+>
+> * pulsar/site2/**website** = pulsar-site site2/**website-next** 
+> 
+> * pulsar/site2/**docs** = pulsar-site/site2/**website-next/docs**
+
+## Update versioned docs
+
+If you want to update versioned docs, go to [pulsar/site2/website/versioned_docs/](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs) to find your desired one.
+
+>❗️**BREAKING CHANGE**
+>
+> If you want to update docs for 2.8.x and later versions, follow the steps below.
+
+1. Update the correct doc set.
+   
+    Update these docs βœ… | DO NOT update these docs ❌
+    |---|---
+    [version-2.8.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.8.x) | - version-2.8.0-deprecated <br><br> - version-2.8.1-deprecated <br><br> - version-2.8.2-deprecated <br><br> - version-2.8.3-deprecated
+    [version-2.9.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.9.x) | - version-2.9.0-deprecated <br><br> - version-2.9.1-deprecated <br><br> - version-2.9.2-deprecated <br><br> - version-2.9.3-deprecated 
+    [version-2.10.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.10.x) |- version-2.10.0-deprecated <br><br> - version-2.10.1-deprecated
+
+    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

Review Comment:
   @SignorMercurio could you please help review the lines 99 - 195 from a technical perspective?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] momo-jun commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
momo-jun commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997641699


##########
site2/doc-guides/preview.md:
##########
@@ -0,0 +1,164 @@
+# Pulsar Content Preview Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains why and how to preview Pulsar content locally with detailed steps and various examples. 
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Content Preview Guide](#pulsar-content-preview-guide)
+  - [Why preview changes locally?](#why-preview-changes-locally)
+  - [How to preview changes locally?](#how-to-preview-changes-locally)
+    - [Prerequisites](#prerequisites)
+    - [Preview doc (markdown) changes](#preview-doc-markdown-changes)
+    - [Preview doc (Java API) changes](#preview-doc-java-api-changes)
+    - [Preview website changes](#preview-website-changes)
+    - [Stop preview](#stop-preview)
+    - [Maintenance info](#maintenance-info)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Why preview changes locally?
+
+It is **required** to preview your changes locally and attach the preview screenshots in your PR description. It brings many benefits, including but not limited to:
+
+* You can test your writings 
+
+    It’s a way to check whether you use the correct [Pulsar Documentation Writing Syntax](https://docs.google.com/document/d/12De2btkDHQVaqUlHjTqERmroMLKGhHdiC7rEttFTyqc/edit#heading=h.y4c4051ki429) and debug issues. You **must ensure** docs can be compiled and published correctly.
+
+* You can get your PR merged more quickly.
+
+    Reviewers know your changes clearly and can speed up the review process.
+
+## How to preview changes locally?
+
+Pulsar documentation is built using Docusaurus. To preview your changes as you edit the files, you can run a local development server that serves your website and reflect the latest changes.
+
+### Prerequisites
+
+To verify docs are built correctly before submitting a contribution, you should set up your local environment to build and display the docs locally.
+
+* Node >= 16.14
+  
+* Yarn >= 1.5
+  
+* Although you can use Linux, macOS, or Windows to build locally the Pulsar documentation, macOS is the preferred build environment as it offers the most complete support for documentation building.
+
+### Preview doc (markdown) changes
+
+Follow these steps to build the doc (markdown) preview on your local machine.
+
+1. Go to the correct repo.
+
+
+    ```
+    cd pulsar/site2/website
+    ```
+
+2. Run the following command to preview changes.
+
+* Preview **master** changes
+
+	If you update master docs, use the following command.
+
+    ```
+    sh start.sh
+    ```
+
+* Preview **historical** changes
+
+    If you update versioned docs, use the following command. 
+    
+    It may take a few more minutes to complete the process.
+
+    ```
+    sh start.sh <version-number> <version-number>
+    ```
+
+    ![alt_text](assets/preview-1.png)
+
+3. By default, a browser window will open at [http://localhost:3000](http://localhost:3000) to show the changes.
+
+    ![alt_text](assets/preview-2.png)
+
+### Preview doc (Java API) changes
+
+Follow these steps to build the doc (Java API) preview on your local machine on the **master** branch.
+
+1. Go to the correct repo.
+
+    ```
+    cd pulsar/site2/tools
+    ```
+
+2. Run the following command to generate the `.html` files.
+
+    ```
+    sh javadoc-gen.sh
+    ```
+
+3. Open the target `.html` file to preview the updates.
+
+    For example, if you change the [ConsumerBuilder.java](http://pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java) for [Pulsar Java docs](https://pulsar.apache.org/api/client/2.11.0/org/apache/pulsar/client/api/ConsumerBuilder.html), you can navigate to the `generated-site/api/client/{version}/org/apache/pulsar/client/api/` directory and open the `ConsumerBuilder.html` file to preview the updates.
+
+### Preview website changes
+
+Pulsar website changes refer to all the changes made to the Pulsar website, including but not limited to the following pages:
+
+* [Release Notes page](https://pulsar.apache.org/release-notes/) βœ…
+* [Ecosystem page](https://pulsar.apache.org/ecosystem) βœ…
+* [Case studies page](https://pulsar.apache.org/case-studies) βœ…
+* …
+* (except docs ❌)
+
+Follow these steps to build the website preview on your local machine.
+
+1. Go to the correct repo.
+
+    ```
+    cd pulsar-site/site2/website-next
+    ```
+
+2️. Run the following command to preview changes.
+
+   * Preview **master** changes
+
+      If you submit changes to master, use the following command.
+
+
+        ```
+        ./preview.sh 
+        ```
+
+   * Preview **historical** changes
+
+      ```
+      ./preview.sh <version-number> <version-number> …
+      ```
+
+      > ❗️ **Note**
+      >
+      > * Use a space between `<version-number> <version-number>`.
+      > 
+      > * If you want to preview multiple version changes, append `<version-number>` with blanks. 
+      > 
+      > For example, `./preview.sh 2.9.1 2.9.2 2.9.3`.
+
+### Stop preview
+
+If you want to stop the preview, use one of the following methods.
+
+* Method 1: Switch to your command-line interface and press **Control+C**.
+  
+* Method 2: Switch to your browser and close the preview page.
+
+### Maintenance info
+
+* For the old Pulsar website, using` yarn start` can preview all (master + historical) changes. However, to speed up the build process, for the new Pulsar website, using `./preview.sh `only preview master changes.

Review Comment:
   ```suggestion
   * 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.
   ```



##########
site2/doc-guides/syntax.md:
##########
@@ -0,0 +1,295 @@
+# Pulsar Documentation Writing Syntax Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains how to write Pulsar documentation using the MDX-compatible markdown syntax.
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Writing Syntax Guide](#pulsar-documentation-writing-syntax-guide)
+  - [Background](#background)
+    - [Why use new markdown syntax?](#why-use-new-markdown-syntax)
+    - [How to test doc changes?](#how-to-test-doc-changes)
+  - [Syntax](#syntax)
+    - [Markdown](#markdown)
+    - [Tab](#tab)
+    - [Code blocks](#code-blocks)
+    - [Admonitions](#admonitions)
+    - [Assets](#assets)
+    - [Indentation & space](#indentation--space)
+    - [Metadata](#metadata)
+    - [Tables](#tables)
+    - [Links](#links)
+      - [Anchor links](#anchor-links)
+      - [Links to internal documentation](#links-to-internal-documentation)
+      - [Links to external documentation](#links-to-external-documentation)
+      - [Link to a specific line of code](#link-to-a-specific-line-of-code)
+    - [Authoritative sources](#authoritative-sources)
+    - [Escape](#escape)
+    - [Headings](#headings)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Background
+
+The Pulsar documentation uses [Markdown](https://www.markdownguide.org/basic-syntax/) as its markup language and [Docusaurus](https://docusaurus.io/) for generating the documentation and website.
+
+> πŸ”΄ **BREAKING CHANGE**
+>
+> From 2022/5/18, you need to use **Markdown syntax that is compatible with MDX**. Otherwise, your changes can not be recognized by MDX and rendered properly. In this case, your PR can not be merged. 
+
+### Why use new markdown syntax?
+
+The new Pulsar website is launched on 2022/5/11. It is upgraded to Docusaurus V2, which uses MDX as the parsing engine. MDX can do much more than just parsing standard Markdown syntax, like rendering React components inside your documents as well. However, **some previous documentation using Markdown syntax is incompatible with MDX**。 Consequently, you need to change the way you write. 
+
+### How to test doc changes?
+
+- You can play with the MDX format in **[MDX Playground](https://mdxjs.com/playground/)** . Write some MDX to find out what it turns into. You can see the rendered result, the generated code, and the intermediary ASTs. This can be helpful for debugging or exploring. 
+
+- For how to test doc changes locally, see [Pulsar Content Preview Guide](./preview.md).
+
+## Syntax
+
+> ❗️**Note**
+> 
+> This guide just highlights **some** important rules and frequently used syntax that is **different from the Markdown syntax used in the previous docs**. For the complete syntax guide, see [Docusaurus - Markdown Features](https://docusaurus.io/docs/next/markdown-features) and [MDX - Markdown](https://mdxjs.com/docs/what-is-mdx/#markdown).
+
+### Markdown 
+
+* **Use Markdown rather than HTML** as much as possible, or else MDX may not recognize it.
+
+    For example, when constructing complex tables, do not use HTML (`<table>`). 
+
+* Use **closing** tags.
+
+    &lt;li>&lt;/li> and &lt;br>&lt;/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> βœ…
+    ```
+    
+    ![alt_text](assets/syntax-1.png)
+    
+    ```
+    <br />xxx β†’ wrap text in "next" line βœ…
+    <br /><br />xxx β†’ wrap text in "next next" line βœ… 
+    ```
+
+    ![alt_text](assets/syntax-2.png)
+
+* 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 for writing multiple tabs before and after. For how to write multiple tabs, see [Tabs](https://docusaurus.io/docs/next/markdown-features/tabs)

Review Comment:
   ```suggestion
   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).
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] momo-jun commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
momo-jun commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997641989


##########
site2/doc-guides/naming.md:
##########
@@ -0,0 +1,216 @@
+# Pulsar Pull Request Naming Convention Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains why you need good PR titles and how you do that with various self​-explanatory examples. 
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Pull Request Naming Convention Guide](#pulsar-pull-request-naming-convention-guide)
+  - [Why do PR titles matter?](#why-do-pr-titles-matter)
+  - [How to write good PR titles?](#how-to-write-good-pr-titles)
+    - [πŸ’‘Quick examples](#πŸ’‘quick-examples)
+    - [`type`](#type)
+    - [`scope`](#scope)
+      - [Pulsar](#pulsar)
+      - [Client](#client)
+    - [`Summary`](#summary)
+    - [Full examples](#full-examples)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Why do PR titles matter?
+
+Engineers and writers submit or review PRs almost every day. 
+
+A PR title is a summary of your changes. 
+
+* Vague, boring, and unclear PR titles decrease team efficiency and productivity. 
+  
+* PR titles should be engaging, easy to understand and readable. 

Review Comment:
   ```suggestion
   * PR titles should be engaging, easy to understand, and readable. 
   ```



##########
site2/doc-guides/label.md:
##########
@@ -0,0 +1,19 @@
+# Pulsar Documentation Label Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide instructs you on how to label your doc PR.
+
+When submitting an issue or PR, you must [provide doc label information](https://github.com/apache/pulsar/blob/master/.github/PULL_REQUEST_TEMPLATE.md#documentation) by **selecting the checkbox**, so that the Bot can label the PR correctly. 
+
+Label name|Usage
+|---|---
+`doc-required`|Use this label to indicate this issue or PR impacts documentation.<br><br> **You have not updated the docs yet**. The docs will be submitted later. 
+`doc-not-needed`| The code changes in this PR do not impact documentation.
+`doc`|This PR contains changes that impact documentation, **no matter whether the changes are in markdown or code files**.
+`doc-complete`|Use this label to indicate the documentation updates are complete.
+`doc-label-missing`|The Bot applies this label when there is no doc label information in the PR if one of the following conditions is met:. <br><br> - You do not provide a doc label. <br><br> - You provide multiple doc labels. <br><br> - You delete backticks (``) in doc labels. <br>For example,<br> [x] `doc-required` βœ… <br> [x] doc-required ❌ <br><br> - You add blanks in square brackets. <br>For example, <br> [x] `doc-required` βœ… <br>[ x ] `doc-required` ❌

Review Comment:
   ```suggestion
   `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` ❌
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] Anonymitaet commented on pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#issuecomment-1280809714

   @D-2-Ed @DaveDuggins @momo-jun could you please review this PR? Thank you!
   
   cc @tisonkun @labuladong @urfreespace 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] momo-jun commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
momo-jun commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997642116


##########
site2/doc-guides/contribution.md:
##########
@@ -0,0 +1,219 @@
+# Pulsar Documentation Contribution Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains the organization of Pulsar documentation and website repos and the workflow of updating various Pulsar docs.
+
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Contribution Guide](#pulsar-documentation-contribution-guide)
+  - [Documentation and website repos](#documentation-and-website-repos)
+    - [Intro to doc and website repos](#intro-to-doc-and-website-repos)
+    - [Relationships between doc and website repos](#relationships-between-doc-and-website-repos)
+  - [Update versioned docs](#update-versioned-docs)
+  - [Update reference docs](#update-reference-docs)
+    - [Update Pulsar configuration docs](#update-pulsar-configuration-docs)
+    - [Update client configuration docs](#update-client-configuration-docs)
+    - [Update CLI tool docs](#update-cli-tool-docs)
+  - [Update client/function matrix](#update-clientfunction-matrix)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Documentation and website repos
+
+This chapter shows the organization of Pulsar documentation and website repos

Review Comment:
   ```suggestion
   This chapter shows the organization of Pulsar documentation and website repos.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] momo-jun commented on pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
momo-jun commented on PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#issuecomment-1285087860

   @Anonymitaet The doc link for how to make contributions to Pulsar documentation on both the [Contribute](https://pulsar.apache.org/contributing/) page and the [About](https://pulsar.apache.org/docs/next/) page is still linking to the google doc. With this new guide published, does it need an update to point to this [new page](https://github.com/apache/pulsar/blob/master/site2/doc-guides/contribution.md)? 
   <img width="1061" alt="image" src="https://user-images.githubusercontent.com/60642177/196886661-409b2ff9-f829-4de2-8202-fb6e5115ae79.png">
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] Anonymitaet commented on pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#issuecomment-1285136501

   @momo-jun yes, I'll update those later.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] momo-jun commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
momo-jun commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997641784


##########
site2/doc-guides/syntax.md:
##########
@@ -0,0 +1,295 @@
+# Pulsar Documentation Writing Syntax Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains how to write Pulsar documentation using the MDX-compatible markdown syntax.
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Writing Syntax Guide](#pulsar-documentation-writing-syntax-guide)
+  - [Background](#background)
+    - [Why use new markdown syntax?](#why-use-new-markdown-syntax)
+    - [How to test doc changes?](#how-to-test-doc-changes)
+  - [Syntax](#syntax)
+    - [Markdown](#markdown)
+    - [Tab](#tab)
+    - [Code blocks](#code-blocks)
+    - [Admonitions](#admonitions)
+    - [Assets](#assets)
+    - [Indentation & space](#indentation--space)
+    - [Metadata](#metadata)
+    - [Tables](#tables)
+    - [Links](#links)
+      - [Anchor links](#anchor-links)
+      - [Links to internal documentation](#links-to-internal-documentation)
+      - [Links to external documentation](#links-to-external-documentation)
+      - [Link to a specific line of code](#link-to-a-specific-line-of-code)
+    - [Authoritative sources](#authoritative-sources)
+    - [Escape](#escape)
+    - [Headings](#headings)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Background
+
+The Pulsar documentation uses [Markdown](https://www.markdownguide.org/basic-syntax/) as its markup language and [Docusaurus](https://docusaurus.io/) for generating the documentation and website.
+
+> πŸ”΄ **BREAKING CHANGE**
+>
+> From 2022/5/18, you need to use **Markdown syntax that is compatible with MDX**. Otherwise, your changes can not be recognized by MDX and rendered properly. In this case, your PR can not be merged. 
+
+### Why use new markdown syntax?
+
+The new Pulsar website is launched on 2022/5/11. It is upgraded to Docusaurus V2, which uses MDX as the parsing engine. MDX can do much more than just parsing standard Markdown syntax, like rendering React components inside your documents as well. However, **some previous documentation using Markdown syntax is incompatible with MDX**。 Consequently, you need to change the way you write. 
+
+### How to test doc changes?
+
+- You can play with the MDX format in **[MDX Playground](https://mdxjs.com/playground/)** . Write some MDX to find out what it turns into. You can see the rendered result, the generated code, and the intermediary ASTs. This can be helpful for debugging or exploring. 
+
+- For how to test doc changes locally, see [Pulsar Content Preview Guide](./preview.md).
+
+## Syntax
+
+> ❗️**Note**
+> 
+> This guide just highlights **some** important rules and frequently used syntax that is **different from the Markdown syntax used in the previous docs**. For the complete syntax guide, see [Docusaurus - Markdown Features](https://docusaurus.io/docs/next/markdown-features) and [MDX - Markdown](https://mdxjs.com/docs/what-is-mdx/#markdown).
+
+### Markdown 
+
+* **Use Markdown rather than HTML** as much as possible, or else MDX may not recognize it.
+
+    For example, when constructing complex tables, do not use HTML (`<table>`). 
+
+* Use **closing** tags.
+
+    &lt;li>&lt;/li> and &lt;br>&lt;/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> βœ…
+    ```
+    
+    ![alt_text](assets/syntax-1.png)
+    
+    ```
+    <br />xxx β†’ wrap text in "next" line βœ…
+    <br /><br />xxx β†’ wrap text in "next next" line βœ… 
+    ```
+
+    ![alt_text](assets/syntax-2.png)
+
+* 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 for writing multiple tabs before and after. For how to write multiple tabs, see [Tabs](https://docusaurus.io/docs/next/markdown-features/tabs)
+
+![alt_text](assets/syntax-3.png)
+
+### 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).
+
+![alt_text](assets/syntax-4.png)
+
+### Assets
+
+Add dash `/` before the asset path.
+
+πŸ™Œ **Examples**
+
+```
+![Page Linking](/assets/page-linking.png)
+```
+
+### Indentation & space
+
+* Use the same indentation for running texts and code blocks. 
+
+  πŸ™Œ **Examples**
+
+  ![alt_text](assets/syntax-5.png)
+
+
+* 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**
+
+  ![alt_text](assets/syntax-6.png)
+
+  > πŸ’‘ **Tip**
+  >
+  > You can set the **Tab Size** in VS Code settings.
+  > 
+  > ![alt_text](assets/syntax-7.png)
+
+* Insert **only an** empty line (not two empty lines or more) between code blocks and running texts. 
+
+  πŸ™Œ **Examples**
+
+  ![alt_text](assets/syntax-8.png)
+
+  ![alt_text](assets/syntax-9.png)
+
+  ![alt_text](assets/syntax-10.png)
+
+### Metadata
+
+If you create a new `.md` file, add quotes for the value of sidebar_label.
+
+πŸ™Œ **Examples**
+
+![alt_text](assets/syntax-11.png)
+
+### 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. 
+
+![alt_text](assets/syntax-12.png)
+
+### 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 does not include the following ❌ 

Review Comment:
   ```suggestion
   - Authoritative sources do not include the following ❌ 
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] Anonymitaet commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r997650203


##########
site2/doc-guides/label.md:
##########
@@ -0,0 +1,19 @@
+# Pulsar Documentation Label Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide instructs you on how to label your doc PR.
+
+When submitting an issue or PR, you must [provide doc label information](https://github.com/apache/pulsar/blob/master/.github/PULL_REQUEST_TEMPLATE.md#documentation) by **selecting the checkbox**, so that the Bot can label the PR correctly. 
+
+Label name|Usage
+|---|---
+`doc-required`|Use this label to indicate this issue or PR impacts documentation.<br><br> **You have not updated the docs yet**. The docs will be submitted later. 
+`doc-not-needed`| The code changes in this PR do not impact documentation.
+`doc`|This PR contains changes that impact documentation, **no matter whether the changes are in markdown or code files**.
+`doc-complete`|Use this label to indicate the documentation updates are complete.
+`doc-label-missing`|The Bot applies this label when there is no doc label information in the PR if one of the following conditions is met:. <br><br> - You do not provide a doc label. <br><br> - You provide multiple doc labels. <br><br> - You delete backticks (``) in doc labels. <br>For example,<br> [x] `doc-required` βœ… <br> [x] doc-required ❌ <br><br> - You add blanks in square brackets. <br>For example, <br> [x] `doc-required` βœ… <br>[ x ] `doc-required` ❌

Review Comment:
   Thanks for your suggestions!
   
   The colon here is OK since IBM Style Guide allows using a colon after the introduction to a vertical list or procedures.
   
   For example,
   
   ```
   When you configure the computer, set the following items:
   β€’ Date and time
   β€’ Drive startup sequence
   β€’ Passwords
   ```
   
   ```
   To install the product, complete the following steps:
   1. Click Install program.
   2. In the wizard, follow the instructions on each page.
   3. Click Finish.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] SignorMercurio commented on a diff in pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
SignorMercurio commented on code in PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#discussion_r998840035


##########
site2/doc-guides/contribution.md:
##########
@@ -0,0 +1,219 @@
+# Pulsar Documentation Contribution Guide
+
+> πŸ‘©πŸ»β€πŸ« **Summary**
+> 
+> This guide explains the organization of Pulsar documentation and website repos and the workflow of updating various Pulsar docs.
+
+
+**TOC**
+
+<!-- TOC -->
+
+- [Pulsar Documentation Contribution Guide](#pulsar-documentation-contribution-guide)
+  - [Documentation and website repos](#documentation-and-website-repos)
+    - [Intro to doc and website repos](#intro-to-doc-and-website-repos)
+    - [Relationships between doc and website repos](#relationships-between-doc-and-website-repos)
+  - [Update versioned docs](#update-versioned-docs)
+  - [Update reference docs](#update-reference-docs)
+    - [Update Pulsar configuration docs](#update-pulsar-configuration-docs)
+    - [Update client configuration docs](#update-client-configuration-docs)
+    - [Update CLI tool docs](#update-cli-tool-docs)
+  - [Update client/function matrix](#update-clientfunction-matrix)
+  - [References](#references)
+
+<!-- /TOC -->
+
+## Documentation and website repos
+
+This chapter shows the organization of Pulsar documentation and website repos
+
+### Intro to doc and website repos
+
+The Pulsar website consists of two parts:
+
+* **Documentation**
+
+  Pulsar documentation repo: [pulsar/site2](https://github.com/apache/pulsar/tree/master/site2)
+
+  ![alt_text](assets/contribution-1.png)
+  
+* **Website** 
+
+  Pulsar website repo: [pulsar-site](https://github.com/apache/pulsar-site)
+
+  ![alt_text](assets/contribution-2.png)
+
+### Relationships between doc and website repos
+
+Type|Repo|Description|PR example
+|---|---|---|---
+Documentation|[pulsar/site2](https://github.com/apache/pulsar/tree/master/site2)|All files related to Pulsar documentation (English) are stored in this repo.|[[feat][doc] add docs for shedding strategy](https://github.com/apache/pulsar/pull/13811)
+Website|[pulsar-site](https://github.com/apache/pulsar-site)|- All files related to the Pulsar website are stored in the **main** branch in this repo. <br><br> - The website is built and put in in the **asf-site-next** branch in this repo.|- [[feat][workflow] add links of doc contribution guides to Pulsar contribution page](https://github.com/apache/pulsar-site/pull/114) <br><br> - [[improve][website] add download links for previous versions](https://github.com/apache/pulsar-site/pull/108)
+
+Files in [pulsar/site2 (master branch)](https://github.com/apache/pulsar/tree/master/site2) are synced to [pulsar-site/website-next (main branch)](https://github.com/apache/pulsar-site/tree/main/site2/website-next) every 6 hours. You can check the sync status and progress at [pulsar-site Actions](https://github.com/apache/pulsar-site/actions/workflows/ci-pulsar-website-docs-sync.yaml).
+
+> **Summary**
+>
+> * pulsar/site2/**website** = pulsar-site site2/**website-next** 
+> 
+> * pulsar/site2/**docs** = pulsar-site/site2/**website-next/docs**
+
+## Update versioned docs
+
+If you want to update versioned docs, go to [pulsar/site2/website/versioned_docs/](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs) to find your desired one.
+
+>❗️**BREAKING CHANGE**
+>
+> If you want to update docs for 2.8.x and later versions, follow the steps below.
+
+1. Update the correct doc set.
+   
+    Update these docs βœ… | DO NOT update these docs ❌
+    |---|---
+    [version-2.8.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.8.x) | - version-2.8.0-deprecated <br><br> - version-2.8.1-deprecated <br><br> - version-2.8.2-deprecated <br><br> - version-2.8.3-deprecated
+    [version-2.9.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.9.x) | - version-2.9.0-deprecated <br><br> - version-2.9.1-deprecated <br><br> - version-2.9.2-deprecated <br><br> - version-2.9.3-deprecated 
+    [version-2.10.x](https://github.com/apache/pulsar/tree/master/site2/website/versioned_docs/version-2.10.x) |- version-2.10.0-deprecated <br><br> - version-2.10.1-deprecated
+
+    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

Review Comment:
   LGTM



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] Anonymitaet commented on pull request #18071: [feat][doc] Add various doc contribution guides

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #18071:
URL: https://github.com/apache/pulsar/pull/18071#issuecomment-1285149215

   > @Anonymitaet The doc link for how to make contributions to Pulsar documentation on both the [Contribute](https://pulsar.apache.org/contributing/) page and the [About](https://pulsar.apache.org/docs/next/) page is still linking to the google doc. With this new guide published, does it need an update to point to this [new page](https://github.com/apache/pulsar/blob/master/site2/doc-guides/contribution.md)? <img alt="image" width="1061" src="https://user-images.githubusercontent.com/60642177/196886661-409b2ff9-f829-4de2-8202-fb6e5115ae79.png">
   
   @momo-jun for the About page, I've updated it in https://github.com/apache/pulsar/pull/18101/files
   for the Contribute page, I'll update it in another PR since it is in the pulsar-site repo.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org