You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@kyuubi.apache.org by "dnskr (via GitHub)" <gi...@apache.org> on 2026/09/08 18:44:28 UTC
[PR] [DOC] Reformat contributing docs from RST to Markdown [kyuubi]
dnskr opened a new pull request, #7717:
URL: https://github.com/apache/kyuubi/pull/7717
### Why are the changes needed?
The changes are needed to unify the format used for documentation, as described in the issue https://github.com/apache/kyuubi/issues/7434.
The PR also fixes broken link to `Building From Source` page: `build.html` -> `building.md`.
The PR **does not** change page contents to ensure an easier review of the migration.
I'm planning to refine the information provided on the pages and refactor them after the migration is completed.
### How was this patch tested?
Tested by building the documentation and comparing the pages against the live site.
### Was this patch assisted by generative AI tooling?
Assisted-by: Qwen Coder
--
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@kyuubi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@kyuubi.apache.org
For additional commands, e-mail: notifications-help@kyuubi.apache.org
Re: [PR] [DOC] Reformat contributing docs from RST to Markdown [kyuubi]
Posted by "wangzhigang1999 (via GitHub)" <gi...@apache.org>.
wangzhigang1999 commented on code in PR #7717:
URL: https://github.com/apache/kyuubi/pull/7717#discussion_r3964340551
##########
docs/contributing/code/get_started.md:
##########
@@ -0,0 +1,85 @@
+<!--
+- Licensed to the Apache Software Foundation (ASF) under one or more
+- contributor license agreements. See the NOTICE file distributed with
+- this work for additional information regarding copyright ownership.
+- The ASF licenses this file to You under the Apache License, Version 2.0
+- (the "License"); you may not use this file except in compliance with
+- the License. You may obtain a copy of the License at
+-
+- http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-->
+
+# Get Started
+
+## Good First Issues
+
+
+
+**Good First Issue** is initiative to curate easy pickings for first-time
+contributors. It helps you locate suitable development tasks with beginner's
+skills required, and finally make your first contribution to Kyuubi.
+
+After solving one or more good first issues, you should be able to
+
+- Find efficient ways to communicate with the community and get help
+- Setup [develop environment](idea_setup.md) on your machine
+- [Build](building.md) Kyuubi from source
+- [Run tests](testing.md) locally
+- [Submit a pull request](https://kyuubi.apache.org/pull_request.html) through Github
+- Be listed in [Apache Kyuubi contributors](https://github.com/apache/kyuubi/graphs/contributors)
+- And most importantly, you can move to the next level and try some tricky issues
+
+:::{note}
+:class: dropdown
+
+Don't linger too long at this stage.
+:::
+
+## Help Wanted Issues
+
+
+
+Issues that maintainers labeled as help wanted are mostly
+
+- sub-tasks of an ongoing shorthanded umbrella
+- non-urgent improvements
+- bug fixes for corner cases
+- feature requests not covered by current technology stack of kyuubi community
+
+Since these problems are not urgent, you can take your time when fixing them.
+
+:::{note}
+:class: dropdown
+
+Help wanted issues may contain easy pickings and tricky ones.
+:::
+
+## Code Contribution Programs
+
+Kyuubi Code Program is a **semi-annual** and **annual** coding program. It's
+a 2-month program and the first round will start in October, 2023.
+
+The program is open to all contributors and newbie-friendly as it will provide
+a mentor to help you get through the sub-tasks.
+
+You will be rewarded with a Kyuubi SWAG, such as a Kyuubi Contributor T-shirt,
+after you complete the program.
+
+
+
+- Status: Planning
+- Duration: 2024.02.01 - 2024.04.01
+- Sponsors: (keeping seats vacant in anticipation)
+
+
+
+- Status: In Progress
+- Duration: 2023.10.01 - 2023.12.01
+- Sponsors: NetEase
Review Comment:
Perhaps we could remove this section, as it has been outdated for a long time.
##########
docs/contributing/doc/style.md:
##########
@@ -0,0 +1,117 @@
+<!--
+- Licensed to the Apache Software Foundation (ASF) under one or more
+- contributor license agreements. See the NOTICE file distributed with
+- this work for additional information regarding copyright ownership.
+- The ASF licenses this file to You under the Apache License, Version 2.0
+- (the "License"); you may not use this file except in compliance with
+- the License. You may obtain a copy of the License at
+-
+- http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-->
+
+# Documentation Style Guide
+
+This guide contains guidelines, not rules. While guidelines are important
+to follow, they are not hard and fast rules. It's important to use your
+own judgement and discretion when creating content, and to depart from the
+guidelines when necessary to improve the quality and effectiveness of your
+content. Ultimately, the goal is to create content that is clear, concise,
+and useful to your audience, and sometimes deviating from the guidelines
+may be necessary to achieve that goal.
+
+## Goals
+
+- Source text files are readable and portable
+- Source diagram files are editable
+- Source files are maintainable over time and across community
+
+## License Header
+
+All original documents should include the ASF license header. All reproduced
+or quoted content should be authorized and attributed to the source.
+
+If you are about to quote some from commercial materials, please refer to
+[ASF 3RD PARTY LICENSE POLICY](https://www.apache.org/legal/resolved.html#asf-3rd-party-license-policy), or consult the Apache Kyuubi PMC to avoid
+legality issues.
+
+## General Style
+
+- Use [ReStructuredText](https://docutils.sourceforge.io/rst.html) or [Markdown](https://en.wikipedia.org/wiki/Markdown) format for text, avoid HTML hacks
Review Comment:
We can remove the ReStructuredText section since we're migrating to Markdown.
##########
docs/contributing/doc/style.md:
##########
@@ -0,0 +1,117 @@
+<!--
+- Licensed to the Apache Software Foundation (ASF) under one or more
+- contributor license agreements. See the NOTICE file distributed with
+- this work for additional information regarding copyright ownership.
+- The ASF licenses this file to You under the Apache License, Version 2.0
+- (the "License"); you may not use this file except in compliance with
+- the License. You may obtain a copy of the License at
+-
+- http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-->
+
+# Documentation Style Guide
+
+This guide contains guidelines, not rules. While guidelines are important
+to follow, they are not hard and fast rules. It's important to use your
+own judgement and discretion when creating content, and to depart from the
+guidelines when necessary to improve the quality and effectiveness of your
+content. Ultimately, the goal is to create content that is clear, concise,
+and useful to your audience, and sometimes deviating from the guidelines
+may be necessary to achieve that goal.
+
+## Goals
+
+- Source text files are readable and portable
+- Source diagram files are editable
+- Source files are maintainable over time and across community
+
+## License Header
+
+All original documents should include the ASF license header. All reproduced
+or quoted content should be authorized and attributed to the source.
+
+If you are about to quote some from commercial materials, please refer to
+[ASF 3RD PARTY LICENSE POLICY](https://www.apache.org/legal/resolved.html#asf-3rd-party-license-policy), or consult the Apache Kyuubi PMC to avoid
+legality issues.
+
+## General Style
+
+- Use [ReStructuredText](https://docutils.sourceforge.io/rst.html) or [Markdown](https://en.wikipedia.org/wiki/Markdown) format for text, avoid HTML hacks
+- Use [draw.io](https://www.diagrams.net/) for drawing or editing an image, and export it as PNG for
+ referencing in document. A pull request should commit both of them
+- Use Kyuubi for short instead of Apache Kyuubi after the first time in the
+ same page
+- Character line limit: 78, except unbreakable ones
+- Prefer lists to tables
+- Prefer unordered list than ordered
+
+## ReStructuredText
Review Comment:
We can remove the ReStructuredText section since we're migrating to 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@kyuubi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@kyuubi.apache.org
For additional commands, e-mail: notifications-help@kyuubi.apache.org
Re: [PR] [DOC] Reformat contributing docs from RST to Markdown [kyuubi]
Posted by "wangzhigang1999 (via GitHub)" <gi...@apache.org>.
wangzhigang1999 commented on code in PR #7717:
URL: https://github.com/apache/kyuubi/pull/7717#discussion_r3964340551
##########
docs/contributing/code/get_started.md:
##########
@@ -0,0 +1,85 @@
+<!--
+- Licensed to the Apache Software Foundation (ASF) under one or more
+- contributor license agreements. See the NOTICE file distributed with
+- this work for additional information regarding copyright ownership.
+- The ASF licenses this file to You under the Apache License, Version 2.0
+- (the "License"); you may not use this file except in compliance with
+- the License. You may obtain a copy of the License at
+-
+- http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-->
+
+# Get Started
+
+## Good First Issues
+
+
+
+**Good First Issue** is initiative to curate easy pickings for first-time
+contributors. It helps you locate suitable development tasks with beginner's
+skills required, and finally make your first contribution to Kyuubi.
+
+After solving one or more good first issues, you should be able to
+
+- Find efficient ways to communicate with the community and get help
+- Setup [develop environment](idea_setup.md) on your machine
+- [Build](building.md) Kyuubi from source
+- [Run tests](testing.md) locally
+- [Submit a pull request](https://kyuubi.apache.org/pull_request.html) through Github
+- Be listed in [Apache Kyuubi contributors](https://github.com/apache/kyuubi/graphs/contributors)
+- And most importantly, you can move to the next level and try some tricky issues
+
+:::{note}
+:class: dropdown
+
+Don't linger too long at this stage.
+:::
+
+## Help Wanted Issues
+
+
+
+Issues that maintainers labeled as help wanted are mostly
+
+- sub-tasks of an ongoing shorthanded umbrella
+- non-urgent improvements
+- bug fixes for corner cases
+- feature requests not covered by current technology stack of kyuubi community
+
+Since these problems are not urgent, you can take your time when fixing them.
+
+:::{note}
+:class: dropdown
+
+Help wanted issues may contain easy pickings and tricky ones.
+:::
+
+## Code Contribution Programs
+
+Kyuubi Code Program is a **semi-annual** and **annual** coding program. It's
+a 2-month program and the first round will start in October, 2023.
+
+The program is open to all contributors and newbie-friendly as it will provide
+a mentor to help you get through the sub-tasks.
+
+You will be rewarded with a Kyuubi SWAG, such as a Kyuubi Contributor T-shirt,
+after you complete the program.
+
+
+
+- Status: Planning
+- Duration: 2024.02.01 - 2024.04.01
+- Sponsors: (keeping seats vacant in anticipation)
+
+
+
+- Status: In Progress
+- Duration: 2023.10.01 - 2023.12.01
+- Sponsors: NetEase
Review Comment:
Perhaps we could remove this section, as it has been outdated for a long time.
##########
docs/contributing/doc/style.md:
##########
@@ -0,0 +1,117 @@
+<!--
+- Licensed to the Apache Software Foundation (ASF) under one or more
+- contributor license agreements. See the NOTICE file distributed with
+- this work for additional information regarding copyright ownership.
+- The ASF licenses this file to You under the Apache License, Version 2.0
+- (the "License"); you may not use this file except in compliance with
+- the License. You may obtain a copy of the License at
+-
+- http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-->
+
+# Documentation Style Guide
+
+This guide contains guidelines, not rules. While guidelines are important
+to follow, they are not hard and fast rules. It's important to use your
+own judgement and discretion when creating content, and to depart from the
+guidelines when necessary to improve the quality and effectiveness of your
+content. Ultimately, the goal is to create content that is clear, concise,
+and useful to your audience, and sometimes deviating from the guidelines
+may be necessary to achieve that goal.
+
+## Goals
+
+- Source text files are readable and portable
+- Source diagram files are editable
+- Source files are maintainable over time and across community
+
+## License Header
+
+All original documents should include the ASF license header. All reproduced
+or quoted content should be authorized and attributed to the source.
+
+If you are about to quote some from commercial materials, please refer to
+[ASF 3RD PARTY LICENSE POLICY](https://www.apache.org/legal/resolved.html#asf-3rd-party-license-policy), or consult the Apache Kyuubi PMC to avoid
+legality issues.
+
+## General Style
+
+- Use [ReStructuredText](https://docutils.sourceforge.io/rst.html) or [Markdown](https://en.wikipedia.org/wiki/Markdown) format for text, avoid HTML hacks
Review Comment:
We can remove the ReStructuredText section since we're migrating to Markdown.
##########
docs/contributing/doc/style.md:
##########
@@ -0,0 +1,117 @@
+<!--
+- Licensed to the Apache Software Foundation (ASF) under one or more
+- contributor license agreements. See the NOTICE file distributed with
+- this work for additional information regarding copyright ownership.
+- The ASF licenses this file to You under the Apache License, Version 2.0
+- (the "License"); you may not use this file except in compliance with
+- the License. You may obtain a copy of the License at
+-
+- http://www.apache.org/licenses/LICENSE-2.0
+-
+- Unless required by applicable law or agreed to in writing, software
+- distributed under the License is distributed on an "AS IS" BASIS,
+- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+- See the License for the specific language governing permissions and
+- limitations under the License.
+-->
+
+# Documentation Style Guide
+
+This guide contains guidelines, not rules. While guidelines are important
+to follow, they are not hard and fast rules. It's important to use your
+own judgement and discretion when creating content, and to depart from the
+guidelines when necessary to improve the quality and effectiveness of your
+content. Ultimately, the goal is to create content that is clear, concise,
+and useful to your audience, and sometimes deviating from the guidelines
+may be necessary to achieve that goal.
+
+## Goals
+
+- Source text files are readable and portable
+- Source diagram files are editable
+- Source files are maintainable over time and across community
+
+## License Header
+
+All original documents should include the ASF license header. All reproduced
+or quoted content should be authorized and attributed to the source.
+
+If you are about to quote some from commercial materials, please refer to
+[ASF 3RD PARTY LICENSE POLICY](https://www.apache.org/legal/resolved.html#asf-3rd-party-license-policy), or consult the Apache Kyuubi PMC to avoid
+legality issues.
+
+## General Style
+
+- Use [ReStructuredText](https://docutils.sourceforge.io/rst.html) or [Markdown](https://en.wikipedia.org/wiki/Markdown) format for text, avoid HTML hacks
+- Use [draw.io](https://www.diagrams.net/) for drawing or editing an image, and export it as PNG for
+ referencing in document. A pull request should commit both of them
+- Use Kyuubi for short instead of Apache Kyuubi after the first time in the
+ same page
+- Character line limit: 78, except unbreakable ones
+- Prefer lists to tables
+- Prefer unordered list than ordered
+
+## ReStructuredText
Review Comment:
We can remove the ReStructuredText section since we're migrating to 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@kyuubi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@kyuubi.apache.org
For additional commands, e-mail: notifications-help@kyuubi.apache.org
Re: [PR] [DOC] Reformat contributing docs from RST to Markdown [kyuubi]
Posted by "dnskr (via GitHub)" <gi...@apache.org>.
dnskr closed pull request #7717: [DOC] Reformat contributing docs from RST to Markdown
URL: https://github.com/apache/kyuubi/pull/7717
--
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@kyuubi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@kyuubi.apache.org
For additional commands, e-mail: notifications-help@kyuubi.apache.org
Re: [PR] [DOC] Reformat contributing docs from RST to Markdown [kyuubi]
Posted by "dnskr (via GitHub)" <gi...@apache.org>.
dnskr commented on PR #7717:
URL: https://github.com/apache/kyuubi/pull/7717#issuecomment-5600369383
Thank you for the review!
Merged to `master` and `branch-1.12`.
--
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@kyuubi.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@kyuubi.apache.org
For additional commands, e-mail: notifications-help@kyuubi.apache.org