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:24 UTC
[kylin] branch doc5.0 updated (1ed6d2c7aa -> 11955d5ad1)
This is an automated email from the ASF dual-hosted git repository.
xxyu pushed a change to branch doc5.0
in repository https://gitbox.apache.org/repos/asf/kylin.git
from 1ed6d2c7aa KYLIN-5242 remove useless contents
new 0957574d63 Refine how to contribute doc
new 11955d5ad1 Add how to subscribe doc
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
website/docs/development/how_to_contribute.md | 86 +++++++++++++--------
.../docs/development/how_to_debug_kylin_in_ide.md | 36 +++++----
website/docs/development/how_to_package.md | 35 +++++++--
.../development/how_to_subscribe_mailing_list.md | 53 +++++++++++++
website/docs/development/how_to_write_doc.md | 52 +++++++------
website/docs/development/images/ISSUE_TEMPLATE.png | Bin 0 -> 680925 bytes
.../docs/development/images/fork_github_repo.png | Bin 0 -> 44798 bytes
.../images/subscribe_mailing_list_1.jpg | Bin 0 -> 112407 bytes
.../images/subscribe_mailing_list_2.jpg | Bin 0 -> 282666 bytes
.../images/subscribe_mailing_list_3.jpg | Bin 0 -> 145424 bytes
.../images/subscribe_mailing_list_4.jpg | Bin 0 -> 214683 bytes
website/docs/development/intro.md | 19 ++++-
website/docusaurus.config.js | 2 +-
13 files changed, 201 insertions(+), 82 deletions(-)
create mode 100644 website/docs/development/how_to_subscribe_mailing_list.md
create mode 100644 website/docs/development/images/ISSUE_TEMPLATE.png
create mode 100644 website/docs/development/images/fork_github_repo.png
create mode 100644 website/docs/development/images/subscribe_mailing_list_1.jpg
create mode 100644 website/docs/development/images/subscribe_mailing_list_2.jpg
create mode 100644 website/docs/development/images/subscribe_mailing_list_3.jpg
create mode 100644 website/docs/development/images/subscribe_mailing_list_4.jpg
[kylin] 02/02: Add how to subscribe doc
Posted by xx...@apache.org.
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 11955d5ad13c9aac368a3cd056eb18c29a76887f
Author: XiaoxiangYu <xx...@apache.org>
AuthorDate: Wed Aug 31 12:48:12 2022 +0800
Add how to subscribe doc
---
website/docs/development/how_to_contribute.md | 38 +++++++++------
.../docs/development/how_to_debug_kylin_in_ide.md | 36 ++++++++------
website/docs/development/how_to_package.md | 35 +++++++++++---
.../development/how_to_subscribe_mailing_list.md | 53 +++++++++++++++++++++
website/docs/development/how_to_write_doc.md | 6 +--
.../docs/development/images/fork_github_repo.png | Bin 0 -> 44798 bytes
.../images/subscribe_mailing_list_1.jpg | Bin 0 -> 112407 bytes
.../images/subscribe_mailing_list_2.jpg | Bin 0 -> 282666 bytes
.../images/subscribe_mailing_list_3.jpg | Bin 0 -> 145424 bytes
.../images/subscribe_mailing_list_4.jpg | Bin 0 -> 214683 bytes
10 files changed, 129 insertions(+), 39 deletions(-)
diff --git a/website/docs/development/how_to_contribute.md b/website/docs/development/how_to_contribute.md
index 4715fe4a11..83cd5142de 100644
--- a/website/docs/development/how_to_contribute.md
+++ b/website/docs/development/how_to_contribute.md
@@ -20,7 +20,7 @@ Apache Kylin is always looking for contributions of not only code, but also user
[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
+### <span id="branch_table">Source Branches</span>
Both code and document are under Git source control. Note the purpose of different branches.
| Branch | Category | Comment |
@@ -45,7 +45,7 @@ Want to know what do different role(like contributor, committer and PMC member)
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.
-6. [Discuss with others in mailing list](#mailing_list) or issue comments, make sure the proposed changes fit in with what others are doing and have planned for the project.
+6. [Discuss with others in mailing list](#discuss_proposal) or issue comments, make sure the proposed changes fit in with what others are doing and have planned for the project.
7. Make code changes in your development branch
- [ ] 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.
@@ -56,7 +56,22 @@ Want to know what do different role(like contributor, committer and PMC member)
### Detailed Description of the steps
-#### <span id="open_issue">Step 4: Pick or create a task</span>
+#### Step 1: Fork Apache Kylin Repo
+
+
+#### Step 2: Clone the fork repo
+```shell
+git clone https://github.com/<YourUserName>/kylin.git
+```
+
+#### Step 3: Create a new development branch
+
+The **new_branch** is determined by which version of Kylin you are working on and [branches table](#branch_table).
+```shell
+git checkout -b <new_branch>
+```
+
+#### <span id="open_issue">Step 5: 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:
@@ -72,29 +87,22 @@ If you want to create a new JIRA for bug or feature, remember to provide enough
- 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 [thread stack](https://issues.apache.org/jira/secure/attachment/13048219/image-2022-08-17-13-17-40-751.png), exception stacktrace 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>
+#### <span id="discuss_proposal">Step 6: Discuss your proposal</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 [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.
+1. Before you sending mail to mailing list, please make sure you have subscribed a mailing list. Please [**check this guide**](how_to_subscribe_mailing_list) if you don't know how to subscribe a mailing list.
2. If you do not [receive the confirmation email](https://www.apache.org/foundation/mailinglists.html#request-confirmation) after sending email to the mail list, the email maybe is shown in your trash mail.
:::
-These are the mailing lists that have been established for kylin project. For each list, there is a subscribe, unsubscribe, and an archive link.
-
-| Mailing List | Subscribe Link | Unsubscribe Link | Archive Link |
-|:-----------------:|:-----------------:|:-----------------:|:-----------------:|
-| user | [subscribe](mailto:user-subscribe@kylin.apache.org) | [unsubscribe](mailto:user-unsubscribe@kylin.apache.org) | [mail archive](https://lists.apache.org/list.html?user@kylin.apache.org) |
-| dev | [subscribe](mailto:dev-subscribe@kylin.apache.org) | [unsubscribe](mailto:dev-unsubscribe@kylin.apache.org) | [mail archive](https://lists.apache.org/list.html?dev@kylin.apache.org) |
-| issue | [subscribe](mailto:issue-subscribe@kylin.apache.org) | [unsubscribe](mailto:issue-unsubscribe@kylin.apache.org) | [mail archive](https://lists.apache.org/list.html?issue@kylin.apache.org) |
-
+
#### <span id="open_pull_request">Step 9: Create a pull request</span>
* Push your code change to your personal repo
@@ -137,7 +145,7 @@ The reviewer needs to review the patch from the following perspectives:
* _API compatibility_: the change SHOULD NOT break public API's functionality and behavior; If an old API need be replaced by the new one, print warning message there.
* _Documentation_: if the Kylin document need be updated together, create another JIRA with "Document" as the component to track. In the document JIRA, attach the doc change patch which is againt the "document" branch.
-:::caution
+:::danger Rules must be obeyed
A patch which doesn't comply with the above rules may not get merged.
:::
diff --git a/website/docs/development/how_to_debug_kylin_in_ide.md b/website/docs/development/how_to_debug_kylin_in_ide.md
index a032cb8795..421a5e2228 100644
--- a/website/docs/development/how_to_debug_kylin_in_ide.md
+++ b/website/docs/development/how_to_debug_kylin_in_ide.md
@@ -18,30 +18,34 @@ last_update:
# How to debug Kylin in IDEA using docker
-## Background
+### Background
#### Why debug Kylin in IDEA using docker
This article aims to introduce a simple and useful way to develop and debug Kylin for developer, and provided similar deployment to user's real scenario.
-This guide assumes you use Laptop such as Macbook to do development work, and have another remote linux server for testing and deployment purpose.
-Windows is not verified at the moment.
+This guide **assumes** you have to the following:
-You have to prepare:
-- Docker Desktop on Mac(and Docker Engine on Linux Server if needed)
-- IntelliJ IDEA and kylin's source code
-
-Tips:
-It is **recommended** to use remote server to deploy Hadoop Cluster, because 7-8 containers may consume a lot of hardware resources and cause your laptop run slower than before.
+- Use a **laptop** with MacOS installed to do development work, and have another **remote linux server** for testing and deployment purpose.
+- Docker Desktop on Mac(Windows is not verified at the moment)
+- Docker Engine on Linux Server(optional)
+- IntelliJ IDEA Community Edition
+- kylin's source code is cloned into some directory in your laptop
#### Deployment architecture
Following is architecture of current deployment.
-## Prepare IDEA and build source code
+### Prepare IDEA and build source code
+
+#### Software Requirement
+
+Please visit [software_reqiurement](how_to_package#software_reqiurement).
+
#### Build source code
- Build back-end source code before your start debug.
```shell
+cd <path-to-kylin-source>
mvn clean install -DskipTests
```
@@ -62,13 +66,17 @@ npm install
-## Prepare the Hadoop Cluster
+### Prepare the Hadoop Cluster
#### Deploy Hadoop Cluster
- Install latest docker desktop in your laptop
- [**Optional**] Install docker engine on remote machine (https://docs.docker.com/engine/install/)
- [**Optional**] If you want to deploy hadoop cluster on remote machine, please set correct `DOCKER_HOST`
+:::tip
+It is recommended to use **remote server** other than laptop to deploy Hadoop Cluster, because 7-8 containers may consume a lot of hardware resources and cause your laptop run slower than before.
+:::
+
```shell
# see more detail at : https://docs.docker.com/compose/reference/envvars/#docker_host
export DOCKER_HOST=ssh://${USER}@${DOCKER_HOST}
@@ -114,7 +122,7 @@ Following output content shows all hadoop component are in health state.
-## Debug Kylin in IDEA
+### Debug Kylin in IDEA
#### Start backend in IDEA
@@ -155,12 +163,12 @@ npm run devproxy
-## Command manual
+### Command manual
1. Use `./dev-support/sandbox/sandbox.sh stop` to stop all containers
2. Use `./dev-support/sandbox/sandbox.sh start` to start all containers
3. Use `./dev-support/sandbox/sandbox.sh ps` to check status of all containers
4. Use `./dev-support/sandbox/sandbox.sh down` to stop all containers and delete them
-## Q&A
+### Q&A
// todo
diff --git a/website/docs/development/how_to_package.md b/website/docs/development/how_to_package.md
index 342800f5e4..5b06284582 100644
--- a/website/docs/development/how_to_package.md
+++ b/website/docs/development/how_to_package.md
@@ -17,15 +17,36 @@ last_update:
# How to package
-### Environment Requirement
+### <span id="software_reqiurement">Software Requirement</span>
-| Software | Comment | Version |
-|---------------| ---------------------------------------------|----------------|
-| Git | Fetch branch name and hash of latest commit | latest |
-| Apache Maven | Build Java and Scala source code | 3.8.2 or latest |
-| Node.js | Build front end | 12.14.0 is recommended ( or 12.x ~ 14.x) |
+| Software | Comment | Version | Download Link |
+|---------------| ---------------------------------------------|----------------|--------------------|
+| Git | Fetch branch name and hash of latest commit | latest | https://git-scm.com/book/en/v2/Getting-Started-Installing-Git |
+| Apache Maven | Build Java and Scala source code | 3.8.2 or latest| https://maven.apache.org/download.cgi |
+| Node.js | Build front end | 12.14.0 is recommended ( or 12.x ~ 14.x) | https://nodejs.org/en/download/ ([How to switch to older node.js](development/how_to_package.md#install_older_node))|
+| JDK | Java Compiler and Development Tools | JDK 1.8.x | https://www.oracle.com/java/technologies/javase/javase8u211-later-archive-downloads.html |
+After installed above software, please do verify **software requirement** by following commands:
+```shell
+$ java -version
+java version "1.8.0_301"
+Java(TM) SE Runtime Environment (build 1.8.0_301-b09)
+Java HotSpot(TM) 64-Bit Server VM (build 25.301-b09, mixed mode)
+
+$ mvn -v
+Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
+Maven home: /Users/xiaoxiang.yu/LacusDir/lib/apache-maven-3.8.2
+Java version: 1.8.0_301, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk1.8.0_301.jdk/Contents/Home/jre
+Default locale: en_CN, platform encoding: UTF-8
+OS name: "mac os x", version: "10.16", arch: "x86_64", family: "mac"
+
+$ node -v
+v12.14.0
+
+$ git version
+git version 2.30.1 (Apple Git-130)
+```
### Options for Packaging Script
| Option | Comment |
@@ -69,7 +90,7 @@ For example, an unofficial package could be `apache-kylin-5.0.0-SNAPSHOT.2022081
./build/release/release.sh -P hadoop3
```
-### How to switch to older node.js
+### <span id="install_older_node">How to switch to older node.js</span>
If you install node.js which is higher than 14.X, I recommended you downgrade to lower version with some tools like https://github.com/nvm-sh/nvm.
diff --git a/website/docs/development/how_to_subscribe_mailing_list.md b/website/docs/development/how_to_subscribe_mailing_list.md
new file mode 100644
index 0000000000..f48653c6c2
--- /dev/null
+++ b/website/docs/development/how_to_subscribe_mailing_list.md
@@ -0,0 +1,53 @@
+---
+title: How to subscribe mailing list
+language: en
+sidebar_label: How to subscribe mailing list
+pagination_label: How to subscribe mailing list
+toc_min_heading_level: 2
+toc_max_heading_level: 6
+keywords:
+ - mailing list
+draft: false
+last_update:
+ date: 08/29/2022
+ author: Xiaoxiang Yu
+---
+
+### Mailing List Table
+These are the mailing lists that have been established for kylin project. For each list, there is a subscribe, unsubscribe, and an archive link.
+
+| Mailing List | Subscribe Link | Unsubscribe Link | Archive Link |
+|:-----------------:|:-----------------:|:-----------------:|:-----------------:|
+| user | [subscribe](mailto:user-subscribe@kylin.apache.org) | [unsubscribe](mailto:user-unsubscribe@kylin.apache.org) | [mail archive](https://lists.apache.org/list.html?user@kylin.apache.org) |
+| dev | [subscribe](mailto:dev-subscribe@kylin.apache.org) | [unsubscribe](mailto:dev-unsubscribe@kylin.apache.org) | [mail archive](https://lists.apache.org/list.html?dev@kylin.apache.org) |
+| issue | [subscribe](mailto:issue-subscribe@kylin.apache.org) | [unsubscribe](mailto:issue-unsubscribe@kylin.apache.org) | [mail archive](https://lists.apache.org/list.html?issue@kylin.apache.org) |
+
+
+### <span id="mailing_list">Subscribe mailing list</span>
+
+#### Step 1: Send subscribe request
+You click the _Subscribe Link_ in above table, and send the simple request(it is ok to leave the title and body with a very short sentence) to the appropriate address .
+
+
+#### Step 2: Receive confirmation reply from ezmlm
+The mailing list management program, [ezmlm](http://untroubled.org/ezmlm/), will send you a reply in 2-10 minutes, ask you to **confirm your subscription**.
+
+Following is a successful case.
+
+
+
+#### Step 3: Send confirmation request by replying to previous email
+Reply to the previous email(it is ok to leave the title and body with a short sentence)
+
+
+#### Step 4: ezmlm acknowledge your confirmation request
+You will receive "Welcome to user/dev@kylin.apache.org" in 2-10 minutes. From now, you have right to send and receive mails from all subscribers of current mailing list.
+
+Following is a successful case.
+
+
+
+
+----
+
+This doc is rewrite based on [apache mailing list doc](https://www.apache.org/foundation/mailinglists.html#subscribing).
\ No newline at end of file
diff --git a/website/docs/development/how_to_write_doc.md b/website/docs/development/how_to_write_doc.md
index a8495eac73..21d223db4b 100644
--- a/website/docs/development/how_to_write_doc.md
+++ b/website/docs/development/how_to_write_doc.md
@@ -20,9 +20,9 @@ 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 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).
+:::info Shortcut for non-programme
+1. This shortcut/way is extreme useful for **non-programmer**. If you found some minor typos or mistakes on a **single** page, you can edit document in browser in this way in 3-15 minutes without preparation.
+2. But if you want to more complex works, like add/edit **several** pages, upload images, or change global config files, please jump to next paragraph: [**Before your work**](#Before_your_work).
:::
1. Just scroll down the page to the bottom and click the `Edit this page`.
diff --git a/website/docs/development/images/fork_github_repo.png b/website/docs/development/images/fork_github_repo.png
new file mode 100644
index 0000000000..7b45000d3c
Binary files /dev/null and b/website/docs/development/images/fork_github_repo.png differ
diff --git a/website/docs/development/images/subscribe_mailing_list_1.jpg b/website/docs/development/images/subscribe_mailing_list_1.jpg
new file mode 100644
index 0000000000..f3c020a177
Binary files /dev/null and b/website/docs/development/images/subscribe_mailing_list_1.jpg differ
diff --git a/website/docs/development/images/subscribe_mailing_list_2.jpg b/website/docs/development/images/subscribe_mailing_list_2.jpg
new file mode 100644
index 0000000000..30e65dae43
Binary files /dev/null and b/website/docs/development/images/subscribe_mailing_list_2.jpg differ
diff --git a/website/docs/development/images/subscribe_mailing_list_3.jpg b/website/docs/development/images/subscribe_mailing_list_3.jpg
new file mode 100644
index 0000000000..cafec65a26
Binary files /dev/null and b/website/docs/development/images/subscribe_mailing_list_3.jpg differ
diff --git a/website/docs/development/images/subscribe_mailing_list_4.jpg b/website/docs/development/images/subscribe_mailing_list_4.jpg
new file mode 100644
index 0000000000..43f95246cc
Binary files /dev/null and b/website/docs/development/images/subscribe_mailing_list_4.jpg differ
[kylin] 01/02: Refine how to contribute doc
Posted by xx...@apache.org.
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',
},