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 06:00:08 UTC
[GitHub] [apisix-website] navendu-pottekkat opened a new pull request #974: docs: Style guide for APISIX documentation
navendu-pottekkat opened a new pull request #974:
URL: https://github.com/apache/apisix-website/pull/974
Fixes https://github.com/apache/apisix/issues/6672
Changes:
- Adds a style guide for APISIX documentation.
- Reorganises the Community tab by consolidating and organising different docs.
- Updates the links to the changed pages.
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836980350
##########
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:
After searching, other product documentation has different requirements on "Names of capitalization styles.". See https://en.wikipedia.org/wiki/Capitalization#Title_case.
For me, before deciding which style we should use, let's confirm the Document Style Guide Proposal first :)
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836404167
##########
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:
So, for the style guide we are proposing, we will be using sentence case for all headings. It is much easier that way because we do not have to ensure title case everywhere and it is difficult to enforce title case everywhere (like in FAQ page).
##########
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:
https://github.com/apache/apisix-website/pull/974#discussion_r836404167
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836146718
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
Review comment:
```suggestion
id: documentation-style-guide
```
##########
File path: website/docs/general/committer-guide.md
##########
@@ -9,31 +9,11 @@ keywords:
description: This article covers some guidelines for Apache APISIX committers. It walks through the type of contributions and the contributor ladder and how contributors can become committers and then PMC members.
---
-This article walks through the guidelines for Apache APISIX contributors.
+This document walks through how Apache APISIX contributors are structured.
-See [Contributor Guide](/docs/general/contributor-guide/) to learn more about the contributing process.
+See [Contributing flow](/docs/general/contributor-guide/) to learn more about the contributing process.
-## What Can I Contribute?
-
-Any and all forms of contributions are welcome! For example you can,
-
-- 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)".
-
-- Join the discussions on the [mailing list](/docs/general/subscribe-guide/).
-
-- Answer questions in [issues](https://github.com/apache/apisix/issues) and [discussions](https://github.com/apache/apisix/discussions).
-
-- Review open [pull requests](https://github.com/apache/apisix/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc).
-
-- Improve the website.
-
-- Improve documentation or write a blog post.
-
-- 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!
-
-## How to become an APISIX committer?
+## How do I become an APISIX committer?
Review comment:
Please use `Apache APISIX`
##########
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
+
+The configuration file is located in `/docs/<locale>/latest/config.json` where locale represents the locale code (language). Refer to [Locale Codes](https://www.science.co.il/language/Locale-codes.php) for more info. Note that locale is always all lowercase.
+
+You can learn more about the sidebar from the [Docusaurus docs](https://v2.docusaurus.io/docs/next/sidebar).
+
+```json
Review comment:
```suggestion
```jsonc
```
##########
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:
+
+ | ✅ | ❌ |
Review comment:
Center aligned?
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836304942
##########
File path: website/blog/2021/06/28/why-we-need-Apache-APISIX.md
##########
@@ -173,6 +173,6 @@ Unification itself is not the goal, but the benefits after unification is the lo
- Company value: Unify technology stack, reduce company operation cost, reduce the difficulty of transitioning to microservices and cloud-native, and accelerate enterprise digital transformation.
-Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/community#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
+Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/join#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
Review comment:
Yes. I missed that. Will update those links.
--
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
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080224965
### <span aria-hidden="true">✅</span> Deploy Preview for *apache-apisix* ready!
| Name | Link |
|---------------------------------|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 7812e999e550105631152bbe969308a08422f600 |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/apache-apisix/deploys/6241b33c2db3f40008e2c0cf |
|<span aria-hidden="true">😎</span> Deploy Preview | https://deploy-preview-974--apache-apisix.netlify.app |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br /><br /><br />_Use your smartphone camera to open QR code link._</details> |
---
_To edit notification comments on pull requests, go to your [Netlify site settings](https://app.netlify.com/sites/apache-apisix/settings/deploys#deploy-notifications)._
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836977397
##########
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:
+
+ | ✅ | ❌ |
Review comment:
Is it?
```
|: Column1 :|: Column 2 :|
```
--
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
[GitHub] [apisix-website] yzeng25 merged pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
yzeng25 merged pull request #974:
URL: https://github.com/apache/apisix-website/pull/974
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836141875
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
After consideration, I could understand why @navendu-pottekkat removes pages like `/community` and `subscribe` and merge them to `/join`, it makes sense to me and is much more straightforward.
To avoid 404 for historical links, I would suggest also supporting redirect `/community` & `/subscribe-xx` to `/join` in the website (For backlinks in other websites), cc @SkyeYoung.
--
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
[GitHub] [apisix-website] navendu-pottekkat edited a comment on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat edited a comment on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080628305
I have left comments and made changes as suggested please check.
I'm having trouble configuring the redirect plugin: https://github.com/apache/apisix-website/pull/974#discussion_r836391455
// @juzhiyuan
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836978168
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
Review comment:
Hi @navendu-pottekkat, usually we need comment authors to Resolve a comment in Apache APISIX Community. :) Before reaching an agreement, let's keep this comment open.
For this comment, "Revert the order could help more on SEO. " I'm not sure on this 😅 bcoz all keywords will be added to this page's Head tag.
--
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
[GitHub] [apisix-website] netlify[bot] commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
netlify[bot] commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080224965
### <span aria-hidden="true">👷</span> Deploy Preview for *apache-apisix* processing.
| Name | Link |
|---------------------------------|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 45b1db7b7f9ca05e855627d13a119422b12ec285 |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/apache-apisix/deploys/62414edb6eb1e7000857bc66 |
--
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
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
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
[GitHub] [apisix-website] avinal commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
avinal commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836304329
##########
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
+
+You can join the Apache APISIX Slack channel in two ways:
+
+- Using [this invite](https://join.slack.com/t/the-asf/shared_invite/zt-vlfbf7ch-HkbNHiU_uDlcH_RvaHv9gQ) (_Please open an issue if this link is expired_).
Review comment:
IG that would be nice
--
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
[GitHub] [apisix-website] avinal commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
avinal commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836297758
##########
File path: website/blog/2021/12/01/apisix-supports-azure-functions.md
##########
@@ -181,4 +181,4 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/azure-functions \
## Summary
-The `azure-functions` plugin is Apache APISIX's second plugin designed for serverless. We are developing other serverless plugins and will feature them with the upcoming Apache APISIX releases. If you are interested, please don't hesitate to [file an issue](https://github.com/apache/apisix/issues/new/choose) to share your opinions. You can talk about your proposals of developing a new plugin in our [mailing list](https://apisix.apache.org/docs/general/community) as well!
+The `azure-functions` plugin is Apache APISIX's second plugin designed for serverless. We are developing other serverless plugins and will feature them with the upcoming Apache APISIX releases. If you are interested, please don't hesitate to [file an issue](https://github.com/apache/apisix/issues/new/choose) to share your opinions. You can talk about your proposals of developing a new plugin in our [mailing list](https://apisix.apache.org/docs/general/join) as well!
Review comment:
```suggestion
The `azure-functions` plugin is Apache APISIX's second plugin designed for serverless. We are developing other serverless plugins and will feature them with the upcoming Apache APISIX releases. If you are interested, please don't hesitate to [file an issue](https://github.com/apache/apisix/issues/new/choose) to share your opinions. You can talk about your proposals for developing a new plugin in our [mailing list](https://apisix.apache.org/docs/general/join) as well!
```
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836139476
##########
File path: website/blog/2021/06/28/why-we-need-Apache-APISIX.md
##########
@@ -173,6 +173,6 @@ Unification itself is not the goal, but the benefits after unification is the lo
- Company value: Unify technology stack, reduce company operation cost, reduce the difficulty of transitioning to microservices and cloud-native, and accelerate enterprise digital transformation.
-Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/community#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
+Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/join#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
Review comment:
I see, after this change https://github.com/apache/apisix-website/pull/974/files#diff-6d85625f2465cb8ff2ebda28c9d6ac33b9930a4988b9be0510d47376665c1585R30, @navendu-pottekkat you could also update Heading IDs :)
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836399218
##########
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:
Good point. I missed it.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080628305
I have left comments and made changes as suggested please check.
I'm having trouble configuring the redirect plugin: https://github.com/apache/apisix-website/pull/974#discussion_r836391455
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837070001
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
Review comment:
I resolve comments as I fix them while making a commit. It helps to track 😅
--
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
[GitHub] [apisix-website] leslie-tsang commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
leslie-tsang commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836123545
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
Seems work fine in preview deployment, which is https://deploy-preview-974--apache-apisix.netlify.app/docs/general/join/
--
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
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080224965
### <span aria-hidden="true">✅</span> Deploy Preview for *apache-apisix* ready!
| Name | Link |
|---------------------------------|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 976173b39093528ebce0bed0542dc6bd06ff78fd |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/apache-apisix/deploys/62414fc49bfc2700090ed367 |
|<span aria-hidden="true">😎</span> Deploy Preview | https://deploy-preview-974--apache-apisix.netlify.app |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br /><br /><br />_Use your smartphone camera to open QR code link._</details> |
---
_To edit notification comments on pull requests, go to your [Netlify site settings](https://app.netlify.com/sites/apache-apisix/settings/deploys#deploy-notifications)._
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836407834
##########
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:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
Review comment:
The normal `----` centers by default I guess.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836258585
##########
File path: website/docs/general/2fa.md
##########
@@ -1,30 +0,0 @@
----
Review comment:
I have moved this to the Contributing Flow guide. As every contributor should go through the contributor flow, this could be part of that flow.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836306133
##########
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:
+
+ | ✅ | ❌ |
Review comment:
You mean the style of the table should be center aligned? Use `---`?
--
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
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080224965
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836391455
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
I tried adding this plugin but it throws an error "cannot mix different versions of joi schemas". I'm not sure why we are getting this error. Can someone else who has worked on this before offer any suggestions?
--
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
[GitHub] [apisix-website] leslie-tsang commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
leslie-tsang commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836123545
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
Seems work fine in preview deployment, which is https://deploy-preview-974--apache-apisix.netlify.app/docs/general/join/
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080698345
> I have left comments and made changes as suggested please check.
>
> I'm having trouble configuring the redirect plugin: [#974 (comment)](https://github.com/apache/apisix-website/pull/974#discussion_r836391455)
>
> // @juzhiyuan
I think this maybe because we are still using an older version of Docusaurus and bumping it up might fix it. But I'm not sure if that is desired or it may break anything.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837037526
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
Yep. I could do that. Let me try changing the versions and see if I'm able to fix this. If not, I will work with @SkyeYoung and setup the redirects.
--
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
[GitHub] [apisix-website] leslie-tsang commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
leslie-tsang commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836126276
##########
File path: website/blog/2021/06/28/why-we-need-Apache-APISIX.md
##########
@@ -173,6 +173,6 @@ Unification itself is not the goal, but the benefits after unification is the lo
- Company value: Unify technology stack, reduce company operation cost, reduce the difficulty of transitioning to microservices and cloud-native, and accelerate enterprise digital transformation.
-Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/community#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
+Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/join#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
Review comment:
Seems we should use `#join-the-slack-channel` instead of `#slack` here, right ? :)
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836132341
##########
File path: website/blog/2021/06/28/why-we-need-Apache-APISIX.md
##########
@@ -173,6 +173,6 @@ Unification itself is not the goal, but the benefits after unification is the lo
- Company value: Unify technology stack, reduce company operation cost, reduce the difficulty of transitioning to microservices and cloud-native, and accelerate enterprise digital transformation.
-Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/community#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
+Last but not least is the APISIX [Slack channel](https://apisix.apache.org/docs/general/join#slack), any questions can be left here or on [Github issue](https://github.com/apache/apisix/issues), there will be someone to respond quickly, thanks again.
Review comment:
The slash is too long IMO 😅 and `join slack` or `community slack` is semantic enough 😉
--
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
[GitHub] [apisix-website] juzhiyuan commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080380403
Link to one discussion: https://github.com/facebook/docusaurus/issues/5838#issuecomment-955278743
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836404704
##########
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:
https://github.com/apache/apisix-website/pull/974#discussion_r836404167
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837255949
##########
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:
Okay. Thanks.
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836141875
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
After consideration, I could understand why @navendu-pottekkat removes pages like `/community` and `subscribe` and merge them to `/join`, it makes sense to me and is much more straightforward.
To avoid 404 for historical links, I would suggest also supporting redirect `/community` & `/subscribe-xx` to `/join` in the website, cc @SkyeYoung.
--
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
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837166949
##########
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:
I am fine with either way.
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837178977
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
Review comment:
OK 😅 Because reviewers may forget which comment has reached agreement 😂
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837257073
##########
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:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
Review comment:
We can stick to the normal left aligned table as all the tables I find are left aligned. It would make it much easier to add new tables as well without having to point this out.
--
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
[GitHub] [apisix-website] avinal commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
avinal commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836300526
##########
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:
+
+ | ✅ | ❌ |
Review comment:
I am not sure how to properly center align in docusauraus, but I have left suggestions for centering in GitHub markdown.
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837071235
##########
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:
+
+ | ✅ | ❌ |
Review comment:
> I looked at some projects and it seems like the left aligned tables are the default. Let's stick with that.
OK to me.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837070364
##########
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:
@juzhiyuan I guess the style guide was accepted and I have added the style guide in this PR.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836402759
##########
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:
It could come under organisation. It shows how the documents are organised and how that organisation is configured in the configuration file. What do you think?
--
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
[GitHub] [apisix-website] juzhiyuan commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1081311744
Hi reviewers, please first review [website/docs/general/documentation-guide.md](https://github.com/apache/apisix-website/pull/974/files#diff-1d6a135b8f8bb730c55306747cced535c9f4570b9c9b528bb6e1d3340e0e1dc7), thanks!
--
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
[GitHub] [apisix-website] juzhiyuan commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1081311307
Don't worry, see https://github.com/apache/apisix-website/pull/974#discussion_r836976994
--
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
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080224965
### <span aria-hidden="true">👷</span> Deploy Preview for *apache-apisix* processing.
| Name | Link |
|---------------------------------|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 7812e999e550105631152bbe969308a08422f600 |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/apache-apisix/deploys/6241b33c2db3f40008e2c0cf |
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1080226965
@juzhiyuan @yzeng25 @avinal @hf400159 Could you please review this PR? I will fix the lint errors.
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836120423
##########
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
+
+You can join the Apache APISIX Slack channel in two ways:
+
+- Using [this invite](https://join.slack.com/t/the-asf/shared_invite/zt-vlfbf7ch-HkbNHiU_uDlcH_RvaHv9gQ) (_Please open an issue if this link is expired_).
+
+- By sending an email to the list ([dev@apisix.apache.org](mailto:dev@apisix.apache.org)) requesting help to join.
Review comment:
Subscribe successfully first, then send mail for help 😄
##########
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
+
+You can join the Apache APISIX Slack channel in two ways:
+
+- Using [this invite](https://join.slack.com/t/the-asf/shared_invite/zt-vlfbf7ch-HkbNHiU_uDlcH_RvaHv9gQ) (_Please open an issue if this link is expired_).
Review comment:
How about linking an `Issue Create Page` here?
##########
File path: website/docs/general/2fa.md
##########
@@ -1,30 +0,0 @@
----
Review comment:
Hi @navendu-pottekkat, this guide is used to remind contributors/maintainers to be more secure. When one wants to have written permission to `apache/*` projects, we have to enable 2FA.
How about adding this section to Committer Guide?
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836117053
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
Hi, @navendu-pottekkat, it's semantic, but this means we will have many pages 404 🤔 I have some ideas:
1. Keep other URLs, and create a page under `xxx/join.`
2. Do some redirect when visit `/community`, `/subscribe-guide`, and so on.
What do you think?
--
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
[GitHub] [apisix-website] membphis commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
membphis commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836118878
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
nice catch
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836406444
##########
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:
https://github.com/apache/apisix-website/pull/974#discussion_r836404167
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837258254
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
Review comment:
@yzeng25 Anyway, I have made this change. You can resolve this conversation.
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#issuecomment-1081641283
Here is the link to the documentation style guide proposed in this PR: https://deploy-preview-974--apache-apisix.netlify.app/docs/general/documentation-style-guide
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837069681
##########
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:
+
+ | ✅ | ❌ |
Review comment:
I looked at some projects and it seems like the left aligned tables are the default. Let's stick with that.
Is there any particular reason to suggest center alignment?
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837181520
##########
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:
> I guess the style guide was accepted
Hi @navendu-pottekkat, the style guide is accepted internally (you and me 😅), we need to invite more reviewers to reach our community's agreement. If no other comments, then it's ok.
For this https://github.com/apache/apisix-website/pull/974#discussion_r836980350, I mean our reviewers may start reviewing other changes than this one, so I left a message: https://github.com/apache/apisix-website/pull/974#issuecomment-1081311744.
As @yzeng25 also thinks it's ok to use both styles, then please resolve this comment. 😉
--
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
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r837180596
##########
File path: website/docs/general/join.md
##########
@@ -0,0 +1,36 @@
+---
+id: join
+title: Join the conversation
+keywords:
+ - Slack
+ - Community
+ - Apache APISIX
Review comment:
I also had that problem a while ago. No worries.
--
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
[GitHub] [apisix-website] avinal commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
avinal commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836301420
##########
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:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
Review comment:
```suggestion
| :--------------: | :--------------: |
```
For centering
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836304244
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
@juzhiyuan Makes sense. Something like this? https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects
Has this been implemented anywhere currently?
--
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
[GitHub] [apisix-website] navendu-pottekkat commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836403063
##########
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:
https://github.com/apache/apisix-website/pull/974#discussion_r836402759
--
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
[GitHub] [apisix-website] juzhiyuan commented on a change in pull request #974: docs: Style guide for APISIX documentation
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836976994
##########
File path: README.md
##########
@@ -1,7 +1,7 @@
# Apache APISIX® Website
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/community)
+[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
Review comment:
Don't worry. Could you help list all broken links after this PR gets merged? And we could seek help from @SkyeYoung to implement this.
--
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