You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kylin.apache.org by xx...@apache.org on 2022/09/01 09:21:25 UTC
[kylin] 01/02: Refine how to contribute doc
This is an automated email from the ASF dual-hosted git repository.
xxyu pushed a commit to branch doc5.0
in repository https://gitbox.apache.org/repos/asf/kylin.git
commit 0957574d63a24022dd2bfdcc213b1a97d89942e2
Author: XiaoxiangYu <xx...@apache.org>
AuthorDate: Tue Aug 30 15:20:46 2022 +0800
Refine how to contribute doc
---
website/docs/development/how_to_contribute.md | 48 +++++++++++++--------
website/docs/development/how_to_write_doc.md | 48 ++++++++++++---------
website/docs/development/images/ISSUE_TEMPLATE.png | Bin 0 -> 680925 bytes
website/docs/development/intro.md | 19 ++++++--
website/docusaurus.config.js | 2 +-
5 files changed, 73 insertions(+), 44 deletions(-)
diff --git a/website/docs/development/how_to_contribute.md b/website/docs/development/how_to_contribute.md
index ede3a86633..4715fe4a11 100644
--- a/website/docs/development/how_to_contribute.md
+++ b/website/docs/development/how_to_contribute.md
@@ -16,16 +16,20 @@ last_update:
author: Tengting Xu, Xiaoxiang Yu
---
-Apache Kylin is always looking for contributions of not only code, but also usage document, performance report, Q&A etc. All kinds of contributions pave the way towards a Kylin Committer. There is opportunity for everyone, especially for those come from analysis and solution background, due to the lacking of content from user and solution perspective.
+Apache Kylin is always looking for contributions of not only code, but also user document, [performance report](https://cwiki.apache.org/confluence/display/KYLIN/Performance+Benchmark+Report+of+Kylin+4.0.0+vs+Kylin3.1.2+on+Hadoop),
+[Q&A](https://cwiki.apache.org/confluence/display/KYLIN/FAQ+Kylin+4.X) etc. All kinds of contributions pave the way towards a [Apache Committer](https://www.apache.org/foundation/how-it-works.html#committers).
+There is opportunity for [newcomers](https://community.apache.org/newcomers/index.html), especially for those come from analysis and solution background, due to the lacking of content from user and solution perspective.
### Source Branches
Both code and document are under Git source control. Note the purpose of different branches.
-* `kylin5`: Development branch for v5.x
-* `doc5.0`: Document branch for v5.x
-* `main`: Maintenance branch for v4.x
-* `kylin3`: Maintenance branch for v2.x
-* `document`: Document branch for v4.x and before
+| Branch | Category | Comment |
+|:------------------|--------------------|:---------------------------------------|
+| **kylin5** | Development branch | **Active** development branch for v5.x |
+| **doc5.0** | Document branch | Document branch for v5.x |
+| **main** | Maintenance branch | Maintenance branch for v4.x |
+| **kylin3** | Maintenance branch | Maintenance branch for v3.x |
+| **document** | Document branch | Document branch for v4.x and before |
-----
@@ -37,7 +41,7 @@ Want to know what do different role(like contributor, committer and PMC member)
### Overall steps
1. Fork [Apache Kylin Repo](https://github.com/apache/kylin) to your repository.
-2. Clone the fork repo to your local. It is recommended to [create a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+2. Clone the fork repo to your local.
3. Create a new development branch locally.
4. [Setup development environment](how_to_debug_kylin_in_ide.md)
5. [Pick or Create a JIRA](#open_issue), describe the feature/enhancement/bug.
@@ -46,29 +50,37 @@ Want to know what do different role(like contributor, committer and PMC member)
- [ ] No strict code style at the moment, but the general rule is keep consistent with existing files. E.g. use 4-space indent for java files.
- [ ] Add test case for your code change as much as possible.
- [ ] Make sure [Run tests](how_to_test.md) can get success, this will ensure your change is in good quality and does not break anything.
- - [ ] Sufficient unit test and integration test is a mandatory part of code change.
-8. Read [CODE REVIEW guidelines](#CodeReviewGuideline) and check if your code does not adhere to the guidelines, you may be asked to redo some work later if you forgot them.
+8. Read [Code Review Guidelines](#CodeReviewGuideline) and check if your code does **adhere to the guidelines**, you may be asked to redo some work later if you forgot them.
9. [Create a pull request](#open_pull_request) for you code change.
10. If you need to update doc, please check out [How to Write Document](./how_to_write_doc) for help.
+### Detailed Description of the steps
#### <span id="open_issue">Step 4: Pick or create a task</span>
There are open tasks waiting to be done, tracked by [KYLIN JIRA](http://issues.apache.org/jira/browse/KYLIN).
If you want to create a new JIRA for bug or feature, remember to provide enough information for the community:
-* A well **summary** for the problem or feature
-* A detail **description**, which may include:
- - the environment of this problem occurred
- - Kylin version
- - Hadoop/Spark version ...
- - the steps to reproduce the problem
- - the error trace or log files (as attachment)
- - the metadata of the model or cube (as attachment)
+* A well **summary** for the problem or feature, like "Failed to read big resource /dict/xxxx at 'Build Dimension Dictionary' Step"
+* A correct **Type** of issue, choose
+ - _New Feature_ , if you want to develop a brand-new function/feature by yourself
+ - _Improvement_ , if you find a way to improve an existent function/feature
+ - _Bug_ , if you find an existent function not works well as expected
+ - _Wish_ , if you want to a new function/feature and wish it will be developed by someone else
* **Affected version**: which Kylin you're using.
+* A detailed **description**, which may include:
+ - the environment of this problem occurred
+ - Kylin version
+ - Hadoop/Spark version ...
+ - the steps to reproduce the problem
+ - the error [stacktrace](https://issues.apache.org/jira/secure/attachment/13048219/image-2022-08-17-13-17-40-751.png) or log files (as attachment)
+ - the metadata of the model or cube (as attachment)
+ - **Root cause**: For bug reports, provide root cause analysis if it is possible, here is an [example for root cause analysis](https://issues.apache.org/jira/browse/KYLIN-4153).
+
+
#### <span id="mailing_list">Step 5: Discuss your proposal in mailing list</span>
Do not forget to discuss in [mailing list](https://www.apache.org/foundation/mailinglists.html) before working on a big task.
-For how to discuss your idea/proposal in mailing list, please check this example : [Example for developer's proposal](https://lists.apache.org/thread/gtcntp4s8k0fz1d4glospq15sycc599x) .
+For how to discuss your idea/proposal in mailing list, please check [guide for ask good question](https://infra.apache.org/contrib-email-tips.html#usefulq) and [example for development's proposal](https://lists.apache.org/thread/gtcntp4s8k0fz1d4glospq15sycc599x) .
:::caution subscribe a mailing list
1. Before you sending mail to mailing list, please make sure you have subscribed a mailing list. Please [check this guide](https://www.apache.org/foundation/mailinglists.html#subscribing) if you don't know how to subscribe a mailing list.
diff --git a/website/docs/development/how_to_write_doc.md b/website/docs/development/how_to_write_doc.md
index f287873019..a8495eac73 100644
--- a/website/docs/development/how_to_write_doc.md
+++ b/website/docs/development/how_to_write_doc.md
@@ -21,7 +21,7 @@ From Kylin 5.0, Kylin community proposed to write documents using [Docusaurus](h
### Shortcut: Edit a single existent page
:::caution
-1. If you found some minor typos or mistakes on a **single** page, you can quickly edit document in browser in quick way.
+1. If you found some minor typos or mistakes on a **single** page, you can edit document in browser in this way in several minutes.
2. But if you want to add/edit **several** pages, upload images, or change global config files, please jump to next paragraph: [Before your work](#Before_your_work).
:::
@@ -42,7 +42,7 @@ Before you add new documentation, please deploy the document compilation environ
There are two steps:
- [Install Node.js](#Install)
-- [Clone Github repo](#Download)
+- [Clone Github Repo](#Download)
#### <span id="Install">Install Node.js</span>
@@ -50,7 +50,7 @@ First, make sure [Node.js](https://nodejs.org/en/download/) version 16.14 or abo
When installing Node.js via **Windows/macOS Installer**, you are recommended to check all checkboxes related to dependencies.
-#### <span id="Download">Clone Github repo</span>
+#### <span id="Download">Clone Github Repo</span>
1. Clone the doc repo to any path you prefer.
@@ -135,17 +135,21 @@ DevelopmentSideBar: [
#### Step 4: Preview in your local machine
-You can preview in your browser, to check exactly what it will look like, please run following commands in the `website` directory of repo folder:
+You can preview in your browser, please run following commands in the `website` directory, then access [doc5.0](http://127.0.0.1:3000) in your browser:
```
npm run start
```
-Then access http://127.0.0.1:3000 in your browser.
+
+:::caution Checklist
+- [ ] Whether **look and feel** meet your expectation?
+- [ ] Whether the link/pictures works fine?
+- [ ] Whether the most important part was highlighted? You may [check this to highlight a paragraph](#highlight_paragraph).
+:::
#### Step 5: Create a pull request
If everything is normal, create a pull request to [Apache Kylin Repo](https://github.com/apache/kylin) and target branch is `doc5.0`.
-
----
### Documentation Specification
@@ -158,14 +162,14 @@ Apache Kylin's website and documentation is using [Docusaurus](https://docusauru
#### Kylin document structure and navigation menu
-The Kylin [website as the Docusaurus source](https://github.com/apache/kylin/tree/document/doc5.0) is maintained under the `doc5.0` branch.
+The Kylin [website material](https://github.com/apache/kylin/tree/doc5.0) is maintained under the `doc5.0` branch.
1. __Home Page__: Home page of Docs
2. __Document__: General docs about Apache Kylin, including _Installation_, _Tutorial_, etc.
-3. __Development__: _"development"_ For developer to contribute, integration with other application and extend Apache Kylin
+3. __Development__: _"development"_ For developer to contribute, to develop, integration with other application and extend Apache Kylin
4. __Download__: _"Download"_ Apache Kylin packages
5. __Community__: Apache kylin Community information
-6. __Blog__: Technic blogs about Apache Kylin
+6. __Blog__: Engineering blogs about Apache Kylin
#### Full doc structure
@@ -226,26 +230,28 @@ doc5.0
More details about structure which managed by Docusaurus, please refer to [Project structure rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
-#### Navigation menu
-
-The menu is managed by Docusaurus collection:
+#### Sidebar
+The Sidebar is managed by __sidebars.js__ , please refer to [Sidebar](https://docusaurus.io/docs/sidebar).
-* __sidebars.js__: All language version menu structure. Docusaurus can hold only one menu file to map any language version menu.
-
-More details about sidebars in Docusaurus, please refer to [Sidebar](https://docusaurus.io/docs/sidebar).
-
-
-#### How to add image
+#### How to add image in doc
All image should be put under _images_ folder, in your document, please using below sample to include image:
```
-
+
```
-
#### How to link to another page
Using relative path for site links, check this [Markdown links](https://docusaurus.io/docs/markdown-features/links)
-#### How to add code highlight
+#### How to add source code in doc
We are using [Code Blocks Doc](https://docusaurus.io/docs/markdown-features/code-blocks) to highlight code syntax, check this doc for more detail sample.
+
+#### <span id="highlight_paragraph">How to highlight a sentence/paragraph</span>
+We recommend you to use [admonitions feature](https://docusaurus.io/docs/markdown-features/admonitions) to highlight a sentence/paragraph, following is a example:
+
+```
+:::caution
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+:::
+```
diff --git a/website/docs/development/images/ISSUE_TEMPLATE.png b/website/docs/development/images/ISSUE_TEMPLATE.png
new file mode 100644
index 0000000000..b1a6c448b0
Binary files /dev/null and b/website/docs/development/images/ISSUE_TEMPLATE.png differ
diff --git a/website/docs/development/intro.md b/website/docs/development/intro.md
index 6a693ac3c6..c33cd133d4 100644
--- a/website/docs/development/intro.md
+++ b/website/docs/development/intro.md
@@ -20,9 +20,20 @@ Check out the [How to Contribute](how_to_contribute.md) document.
### Source Repository
Apache Kylin™ source code is version controlled using Git version control:
-Commits Summary
-Source Repo: https://github.com/apache/kylin
-Mirrored to Gitbox: https://gitbox.apache.org/repos/asf?p=kylin.git
+
+| Repository | Link |
+|:------------------|:------------------------------------------------|
+| Commits | https://github.com/apache/kylin/commits/kylin5 |
+| Source Repo | https://github.com/apache/kylin/ |
+| Mirrored to Gitbox| https://gitbox.apache.org/repos/asf?p=kylin.git |
+
### Issue Tracking
-Track issues on the “Kylin” Project on the [Apache JIRA](http://issues.apache.org/jira/browse/KYLIN)
\ No newline at end of file
+Track issues on the **Kylin Project** on the [Apache JIRA](http://issues.apache.org/jira/browse/KYLIN)
+
+### Wiki
+Please check [How to contribute wiki](https://cwiki.apache.org/confluence/display/KYLIN/How+to+contribute+wiki) .
+
+### Roadmap
+
+Please check [Roadmap of Kylin 5.0](./roadmap.md)
\ No newline at end of file
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 47612ab1af..008c020c89 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -149,7 +149,7 @@ const config = {
},
{
type: 'doc',
- docId: 'development/how_to_contribute',
+ docId: 'development/roadmap',
position: 'left',
label: 'Development',
},