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

[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