You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/03/28 09:04:34 UTC
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #974: docs: Style guide for APISIX documentation
yzeng25 commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836179023
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
Review comment:
Revert the order could help more on SEO. Think of how you would search for certain contents via Google, it is always `Apache APISIX` + `other keywords`.
```suggestion
- Apache APISIX
- Slack
- Community
```
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document is intended for contributors to APISIX's documentation and should be followed to ensure consistency.
+
+To learn more about contributing, see [Contributing flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful without being frivolous. Learn more on [Voice and tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts) to learn more.
+- Identify the intended audience and write for them. Find the common ground for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
+ | URL | url |
+ | API | api |
+ | APISIX Dashboard | Apisix dashboard |
+ | gRPC | GRPC/grpc |
+
+## Formatting, punctuation and organization
+
+- Use sentence case for all headings and subheadings.
+- Use advanced markdown features and admonitions provided by Docusaurus when necessary:
+ - Use [tabs](https://docusaurus.io/docs/next/markdown-features/tabs) and [synced tabs](https://docusaurus.io/docs/next/markdown-features/tabs#syncing-tab-choices) when you have to show multiple paths based on a user's configuration or environment.
+ - Use [code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) to display code. Add the file being modified as the title of the codeblock (for example, `coonf/config.yaml`). Use line highlighting to focus the attention of the use while explaining code.
+ - Use [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) to highlight important information. Use them as suggested below:
+ - Note: for general information you want to stand out.
+ - Tip: to give users bonus tips that build on top of the rest of the content. Can be ignored generally.
+ - Important: to give extra emphasis to general information.
+ - Warning: to highlight possibilities of loss of configuration or data.
+ - Danger: user should be very careful about what is mentioned in the block. Use only in cases of maximum severity.
+- Use tables to convey appropriate information easily. See [how they are used in FAQ](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix).
+- Use relative paths within markdown files `../xxx/xxx` instead of absolute paths.
+
+### Directory structure
+
+The docs are organized as shown below. To create a new page, create a new file in the latest folder of the language you are writing the doc in.
+
+```text
+/docs
+├── assets
+│ ├── images
+│ │ ├── xxxxx.png
+│ └── other
+│ └── xxxxx.xxx
+├── en
+│ └── latest
+│ ├── doc1.md
+│ ├── folder
+│ │ └── doc2.md
+│ │ └── folder2
+│ │ └── doc3.md
+│ └── config.json
+├── es
+│ └── latest
+│ └── ...
+└── zh
+ └── latest
+ └── ...
+```
+
+### Configuration file
Review comment:
I guess this could be `##` instead of `###`, since it is not much related to "Formatting, punctuation and organization“ section.
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -1,33 +1,37 @@
---
id: contributor-guide
-title: Contributor Guide
+title: Contributing flow
keywords:
- API gateway
- APISIX
- Apache APISIX
- contributor guide
-description: This article is a set of guidelines for Apache APISIX contributors, including things that a contributor can do and how to do it well.
+description: Guidelines for Apache APISIX contributors.
---
-Please follow this guide to [report bugs](#submitting-an-issue), [submit suggestions](#submitting-an-issue), or [submit PRs](#open-a-pull-request).
+This document describes the general flow for contributing to APISIX repos.
-## Submitting an Issue
+## What can I contribute?
Review comment:
```suggestion
## What Can I Contribute?
```
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -37,28 +41,19 @@ You can also contribute by fixing one of the [open issues](https://github.com/ap
3. Connect with a [Committer or PMC](/team) for providing feedback on your issue and reviewing your PR.
-### Good First Issues
+### Good first issues
-Issues labelled "good first issues" are low hanging fruits that are easy to fix. These issues can help you make your first contributions to Apache APISIX®.
+Issues labelled "good first issues" are low hanging fruits that are easy to fix. These issues can help you make your first contributions to APISIX.
-The list below contains such issues spanning across all the repos in Apache APISIX®.
+To start, you can go through this [curated list of "good first issues"](/contribute).
-- [Apache APISIX®](https://github.com/apache/apisix/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Ingress Controller](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® dashboard](https://github.com/apache/apisix-dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Helm Chart](https://github.com/apache/apisix-helm-chart/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Docker distribution for Apache APISIX®](https://github.com/apache/apisix-docker/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Website](https://github.com/apache/apisix-website/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Java Plugin Runner](https://github.com/apache/apisix-java-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
-- [Apache APISIX® Go Plugin Runner](https://github.com/apache/apisix-go-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
-
-## Git Flow
+## Git flow
To contribute code or documentation, setup your local machine for development.
### Fork the repo and clone your fork
Review comment:
```suggestion
### Fork the Repo and Clone Your Fork
```
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document is intended for contributors to APISIX's documentation and should be followed to ensure consistency.
+
+To learn more about contributing, see [Contributing flow](contributor-guide.md).
+
+## Tone, content and audience
Review comment:
```suggestion
## Tone, Content and Audience
```
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document is intended for contributors to APISIX's documentation and should be followed to ensure consistency.
+
+To learn more about contributing, see [Contributing flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful without being frivolous. Learn more on [Voice and tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts) to learn more.
+- Identify the intended audience and write for them. Find the common ground for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
+ | URL | url |
+ | API | api |
+ | APISIX Dashboard | Apisix dashboard |
+ | gRPC | GRPC/grpc |
+
+## Formatting, punctuation and organization
+
+- Use sentence case for all headings and subheadings.
+- Use advanced markdown features and admonitions provided by Docusaurus when necessary:
+ - Use [tabs](https://docusaurus.io/docs/next/markdown-features/tabs) and [synced tabs](https://docusaurus.io/docs/next/markdown-features/tabs#syncing-tab-choices) when you have to show multiple paths based on a user's configuration or environment.
+ - Use [code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) to display code. Add the file being modified as the title of the codeblock (for example, `coonf/config.yaml`). Use line highlighting to focus the attention of the use while explaining code.
+ - Use [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) to highlight important information. Use them as suggested below:
+ - Note: for general information you want to stand out.
+ - Tip: to give users bonus tips that build on top of the rest of the content. Can be ignored generally.
+ - Important: to give extra emphasis to general information.
+ - Warning: to highlight possibilities of loss of configuration or data.
+ - Danger: user should be very careful about what is mentioned in the block. Use only in cases of maximum severity.
+- Use tables to convey appropriate information easily. See [how they are used in FAQ](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix).
+- Use relative paths within markdown files `../xxx/xxx` instead of absolute paths.
+
+### Directory structure
Review comment:
I guess this could be `##` instead of `###`, since it is not much related to "Formatting, punctuation and organization“ section.
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document is intended for contributors to APISIX's documentation and should be followed to ensure consistency.
+
+To learn more about contributing, see [Contributing flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful without being frivolous. Learn more on [Voice and tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts) to learn more.
+- Identify the intended audience and write for them. Find the common ground for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
+ | URL | url |
+ | API | api |
+ | APISIX Dashboard | Apisix dashboard |
+ | gRPC | GRPC/grpc |
+
+## Formatting, punctuation and organization
+
+- Use sentence case for all headings and subheadings.
+- Use advanced markdown features and admonitions provided by Docusaurus when necessary:
+ - Use [tabs](https://docusaurus.io/docs/next/markdown-features/tabs) and [synced tabs](https://docusaurus.io/docs/next/markdown-features/tabs#syncing-tab-choices) when you have to show multiple paths based on a user's configuration or environment.
+ - Use [code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) to display code. Add the file being modified as the title of the codeblock (for example, `coonf/config.yaml`). Use line highlighting to focus the attention of the use while explaining code.
+ - Use [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) to highlight important information. Use them as suggested below:
+ - Note: for general information you want to stand out.
+ - Tip: to give users bonus tips that build on top of the rest of the content. Can be ignored generally.
+ - Important: to give extra emphasis to general information.
+ - Warning: to highlight possibilities of loss of configuration or data.
+ - Danger: user should be very careful about what is mentioned in the block. Use only in cases of maximum severity.
+- Use tables to convey appropriate information easily. See [how they are used in FAQ](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix).
+- Use relative paths within markdown files `../xxx/xxx` instead of absolute paths.
+
+### Directory structure
+
+The docs are organized as shown below. To create a new page, create a new file in the latest folder of the language you are writing the doc in.
Review comment:
```suggestion
The documents are organized as shown below. To create a new page, create a new file in the latest folder of the language you are writing the document in.
```
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document is intended for contributors to APISIX's documentation and should be followed to ensure consistency.
+
+To learn more about contributing, see [Contributing flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful without being frivolous. Learn more on [Voice and tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts) to learn more.
+- Identify the intended audience and write for them. Find the common ground for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
+ | URL | url |
+ | API | api |
+ | APISIX Dashboard | Apisix dashboard |
+ | gRPC | GRPC/grpc |
+
+## Formatting, punctuation and organization
+
+- Use sentence case for all headings and subheadings.
+- Use advanced markdown features and admonitions provided by Docusaurus when necessary:
+ - Use [tabs](https://docusaurus.io/docs/next/markdown-features/tabs) and [synced tabs](https://docusaurus.io/docs/next/markdown-features/tabs#syncing-tab-choices) when you have to show multiple paths based on a user's configuration or environment.
+ - Use [code blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) to display code. Add the file being modified as the title of the codeblock (for example, `coonf/config.yaml`). Use line highlighting to focus the attention of the use while explaining code.
+ - Use [admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) to highlight important information. Use them as suggested below:
+ - Note: for general information you want to stand out.
+ - Tip: to give users bonus tips that build on top of the rest of the content. Can be ignored generally.
+ - Important: to give extra emphasis to general information.
+ - Warning: to highlight possibilities of loss of configuration or data.
+ - Danger: user should be very careful about what is mentioned in the block. Use only in cases of maximum severity.
+- Use tables to convey appropriate information easily. See [how they are used in FAQ](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix).
+- Use relative paths within markdown files `../xxx/xxx` instead of absolute paths.
+
+### Directory structure
+
+The docs are organized as shown below. To create a new page, create a new file in the latest folder of the language you are writing the doc in.
+
+```text
+/docs
+├── assets
+│ ├── images
+│ │ ├── xxxxx.png
+│ └── other
+│ └── xxxxx.xxx
+├── en
+│ └── latest
+│ ├── doc1.md
+│ ├── folder
+│ │ └── doc2.md
+│ │ └── folder2
+│ │ └── doc3.md
+│ └── config.json
+├── es
+│ └── latest
+│ └── ...
+└── zh
+ └── latest
+ └── ...
Review comment:
This tree is somewhat inaccurate. We don't have the `es` part now. You can delete line 74-77 for now, see https://github.com/apache/apisix/tree/master/docs.
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -37,28 +41,19 @@ You can also contribute by fixing one of the [open issues](https://github.com/ap
3. Connect with a [Committer or PMC](/team) for providing feedback on your issue and reviewing your PR.
-### Good First Issues
+### Good first issues
-Issues labelled "good first issues" are low hanging fruits that are easy to fix. These issues can help you make your first contributions to Apache APISIX®.
+Issues labelled "good first issues" are low hanging fruits that are easy to fix. These issues can help you make your first contributions to APISIX.
-The list below contains such issues spanning across all the repos in Apache APISIX®.
+To start, you can go through this [curated list of "good first issues"](/contribute).
-- [Apache APISIX®](https://github.com/apache/apisix/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Ingress Controller](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® dashboard](https://github.com/apache/apisix-dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Helm Chart](https://github.com/apache/apisix-helm-chart/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Docker distribution for Apache APISIX®](https://github.com/apache/apisix-docker/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Website](https://github.com/apache/apisix-website/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Apache APISIX® Java Plugin Runner](https://github.com/apache/apisix-java-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
-- [Apache APISIX® Go Plugin Runner](https://github.com/apache/apisix-go-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
-
-## Git Flow
+## Git flow
Review comment:
```suggestion
## Git Flow
```
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -134,4 +129,24 @@ See [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow#
5. Wait for your PR to be approved and merged.
-6. Congratulate yourself for being an official contributor of Apache APISIX®!
+6. Congratulate yourself for being an official contributor of Apache APISIX!
+
+## Two-Factor Authentication (2FA)
+
+Two-Factor Authentication (2FA) refers to the authentication method that combines both a password and an object (credit card, SMS, tokens, or biomarkers as fingerprint) to identify a user.
+
+To ensure the security of the committer’s account, we need you to [configure 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) while signing in to contribute code on GitHub. For more details, please refer to [Securing your account with two-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa).
+
+**Note**: If 2FA is not enabled, you are liable to be removed from the project and would not be able to access Apache APISIX's repositories.
+
+### Configuring 2FA on GitHub
+
+You can configure 2FA using a [mobile app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app) or via [text message](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages).
+
+GitHub recommends using a time-based-one-time password (TOTP) mobile application to configure 2FA. Read [Configuring two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) for detailed information.
+
+### Submitting code
Review comment:
```suggestion
### Submitting Code
```
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document is intended for contributors to APISIX's documentation and should be followed to ensure consistency.
+
+To learn more about contributing, see [Contributing flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful without being frivolous. Learn more on [Voice and tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts) to learn more.
+- Identify the intended audience and write for them. Find the common ground for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
+ | URL | url |
+ | API | api |
+ | APISIX Dashboard | Apisix dashboard |
+ | gRPC | GRPC/grpc |
+
+## Formatting, punctuation and organization
Review comment:
```suggestion
## Formatting, Punctuation and Organization
```
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
+description: Join the Apache APISIX community and get involved in the conversations.
+---
+
+
+Apache APISIX is a project maintained by community members under the Apache Software Foundation and abide by [ASF's code of conduct](https://www.apache.org/foundation/policies/conduct.html).
+
+We have a transparent and inclusive community where you can join in and contribute to the discussion.
+
+### Subscribe to the Mailing List
+
+You can subscribe to the Apache APISIX mailing list to discuss issues, suggest new ideas, and participate in other community discussions.
+
+1. To subscribe to the mailing list, first, send an email to dev-subscribe@apisix.apache.org.
+
+2. Once you send the email, you will receive a confirmation e-mail from dev-help@apisix.apache.org.
+
+3. Reply to this email to confirm your subscription.
+
+4. Once you confirm, you will receive a welcome email with instructions on using and communicating over the mailing list.
+
+5. To view archived emails from the mailing list, check out the [history](https://lists.apache.org/list.html?apisix.apache.org).
+
+### Join the Slack Channel
Review comment:
I think `##` is more appropriate here.
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
+description: Join the Apache APISIX community and get involved in the conversations.
+---
+
+
+Apache APISIX is a project maintained by community members under the Apache Software Foundation and abide by [ASF's code of conduct](https://www.apache.org/foundation/policies/conduct.html).
+
+We have a transparent and inclusive community where you can join in and contribute to the discussion.
+
+### Subscribe to the Mailing List
Review comment:
I think `##` is more appropriate here.
##########
File path: website/docs/general/sidebars.json
##########
@@ -1,16 +1,27 @@
{
"docs": {
- "General": [
- "community",
+ "Community": [
+ "join",
"events",
- "contributor-guide",
- "committer-guide",
- "subscribe-guide",
- "blog",
- "security",
- "2fa",
- "release-guide",
- "integrate-with-project-docs"
+ {
+ "type": "category",
+ "label": "Contribute to APISIX",
+ "items": [
+ "submit-issue",
+ "contributor-guide",
+ "blog",
+ "security",
+ "committer-guide"
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Process and style guides",
+ "items": [
+ "documentation-guide",
Review comment:
If you decide to update https://github.com/apache/apisix-website/pull/974/files#r836146718, please update it here as well.
```suggestion
"documentation-style-guide",
```
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -37,28 +41,19 @@ You can also contribute by fixing one of the [open issues](https://github.com/ap
3. Connect with a [Committer or PMC](/team) for providing feedback on your issue and reviewing your PR.
-### Good First Issues
+### Good first issues
Review comment:
```suggestion
### Good First Issues
```
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -1,33 +1,37 @@
---
id: contributor-guide
-title: Contributor Guide
+title: Contributing flow
keywords:
- API gateway
- APISIX
- Apache APISIX
- contributor guide
-description: This article is a set of guidelines for Apache APISIX contributors, including things that a contributor can do and how to do it well.
+description: Guidelines for Apache APISIX contributors.
---
-Please follow this guide to [report bugs](#submitting-an-issue), [submit suggestions](#submitting-an-issue), or [submit PRs](#open-a-pull-request).
+This document describes the general flow for contributing to APISIX repos.
-## Submitting an Issue
+## What can I contribute?
-Before submitting an issue, try solving the problem through a comprehensive search.
+Any and all forms of contributions are welcome! For example you can,
-[Open issues](https://github.com/apache/apisix/issues) and the [discussions forum](https://github.com/apache/apisix/discussions) are good places to search for solutions before opening an issue.
+- Fix issues tagged "[good first issue](/docs/general/contributor-guide/#good-first-issues)" or "[help wanted](https://github.com/apache/apisix/issues?q=is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc)".
-1. Check the [open issues](https://github.com/apache/apisix/issues) to avoid duplication.
+- Join the discussions on the [mailing list](/docs/general/join/).
-2. Create a [new issue](https://github.com/apache/apisix/issues/new/choose) and choose the type of issue.
+- Answer questions in [issues](https://github.com/apache/apisix/issues) and [discussions](https://github.com/apache/apisix/discussions).
-3. Define the issue with a clear and descriptive title.
+- Review open [pull requests](https://github.com/apache/apisix/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc).
-4. Fill in necessary information according to the template.
+- Improve the website.
-5. Engage in the discussions in the issue and provide more information if necessary.
+- Improve documentation or write a blog post.
-## Choosing an Issue to Work On
+- Any other form of code or non-code contribution.
+
+If you would like to contribute, let us know by sending an email to dev@apisix.apache.org!
+
+## Choosing an issue to work on
Review comment:
Seems like we are losing some consistency here. I see other docs' section titles are in terms of first letter capitalized.
```suggestion
## Choosing an Issue to Work on
```
##########
File path: website/docs/general/contributor-guide.md
##########
@@ -1,33 +1,37 @@
---
id: contributor-guide
-title: Contributor Guide
+title: Contributing flow
keywords:
- API gateway
- APISIX
- Apache APISIX
- contributor guide
-description: This article is a set of guidelines for Apache APISIX contributors, including things that a contributor can do and how to do it well.
+description: Guidelines for Apache APISIX contributors.
---
-Please follow this guide to [report bugs](#submitting-an-issue), [submit suggestions](#submitting-an-issue), or [submit PRs](#open-a-pull-request).
+This document describes the general flow for contributing to APISIX repos.
-## Submitting an Issue
+## What can I contribute?
-Before submitting an issue, try solving the problem through a comprehensive search.
+Any and all forms of contributions are welcome! For example you can,
-[Open issues](https://github.com/apache/apisix/issues) and the [discussions forum](https://github.com/apache/apisix/discussions) are good places to search for solutions before opening an issue.
+- Fix issues tagged "[good first issue](/docs/general/contributor-guide/#good-first-issues)" or "[help wanted](https://github.com/apache/apisix/issues?q=is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc)".
Review comment:
```suggestion
- Fix issues tagged with "[good first issue](/docs/general/contributor-guide/#good-first-issues)" or "[help wanted](https://github.com/apache/apisix/issues?q=is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc)".
```
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org