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


The following commit(s) were added to refs/heads/doc5.0 by this push:
     new 6a9543f165 Update screenshots, refine how to contribute doc
6a9543f165 is described below

commit 6a9543f1659f412a1319387f3b0a5fe0b691baa4
Author: XiaoxiangYu <x...@apache.org>
AuthorDate: Tue Sep 6 17:17:41 2022 +0800

    Update screenshots, refine how to contribute doc
---
 website/docs/development/how_to_contribute.md      |  45 ++++++----
 .../docs/development/how_to_debug_kylin_in_ide.md  |  99 ++++++++++++---------
 website/docs/development/how_to_package.md         |  23 ++++-
 website/docs/development/how_to_write_doc.md       |  39 ++++++--
 .../images/IDEA_Install_Scala_plugin.png           | Bin 0 -> 333636 bytes
 .../development/images/IDEA_Notify_Install_SDK.png | Bin 0 -> 406049 bytes
 .../images/IDEA_RELOAD_ALL_MAVEN_PROJECT.png       | Bin 0 -> 474625 bytes
 .../docs/development/images/IDEA_SANDBOX_INIT.png  | Bin 0 -> 490586 bytes
 .../docs/development/images/OPEN_KYLIN_PROJECT.png | Bin 0 -> 187986 bytes
 .../development/images/PROJECT_BUILD_SUCCEED.png   | Bin 0 -> 1005844 bytes
 .../docs/development/images/RUN_KYLIN_IN_IDEA.png  | Bin 0 -> 23851 bytes
 .../development/images/SPARDER_SUCCEED_IN_IDE.png  | Bin 0 -> 304300 bytes
 .../docs/development/images/how-to-debug-05.png    | Bin 63470 -> 0 bytes
 .../docs/development/images/how-to-debug-06.png    | Bin 934419 -> 0 bytes
 website/sidebars.js                                |   4 +
 15 files changed, 144 insertions(+), 66 deletions(-)

diff --git a/website/docs/development/how_to_contribute.md 
b/website/docs/development/how_to_contribute.md
index 83cd5142de..27f5dcdaf3 100644
--- a/website/docs/development/how_to_contribute.md
+++ b/website/docs/development/how_to_contribute.md
@@ -40,9 +40,9 @@ 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.
-3. Create a new development branch locally.
+1. [Fork Kylin Repo to your repository](#fork_repo) 
(https://github.com/apache/kylin).
+2. [Clone the fork repo to your local](#clone_repo).
+3. [Create a new development branch locally](#create_branch).
 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](#discuss_proposal) or issue comments, 
make sure the proposed changes fit in with what others are doing and have 
planned for the project.
@@ -54,21 +54,32 @@ Want to know what do different role(like contributor, 
committer and PMC member)
 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
+### Detailed Description
 
-#### Step 1: Fork Apache Kylin Repo  
+#### <span id="fork_repo">Step 1: Fork Apache Kylin Repo</span> 
+Visit https://github.com/apache/kylin in your browser, and click the **Fork** 
button.
 ![](images/fork_github_repo.png)
 
-#### Step 2: Clone the fork repo
+#### <span id="clone_repo">Step 2: Clone the fork repo</span>
 ```shell
-git clone https://github.com/<YourUserName>/kylin.git
+git clone https://github.com/<YourUserName>/kylin.git 
 ```
 
-#### Step 3: Create a new development branch
+#### <span id="create_branch">Step 3: Create a new development branch</span>
 
-The **new_branch** is determined by which version of Kylin you are working on 
and [branches table](#branch_table).
+The **base_branch** is determined by which version of Kylin you want to work 
on and [branches table](#branch_table). For better understanding of Git 
operations, please check [Contributing to a 
Project](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
 ```shell
-git checkout -b <new_branch>
+## check out to base branch you want to work on
+git checkout <base_branch>
+
+## create a development branch based on base branch
+git checkout -b <development_branch>
+```
+
+For example, if I want to fix some issue for Kylin 5.0.0-alpha, you could 
execute following command:
+```shell
+git checkout kylin5
+git checkout -b fix_some_issue
 ```
 
 #### <span id="open_issue">Step 5: Pick or create a task</span>
@@ -93,6 +104,10 @@ If you want to create a new JIRA for bug or feature, 
remember to provide enough
 
 ![](images/ISSUE_TEMPLATE.png)
 
+:::caution report a possible vulnerability
+For a possible vulnerability, do not use JIRA, please follow the guide 
https://apache.org/security/committers.html#report .
+:::
+
 #### <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) .
@@ -107,21 +122,20 @@ For how to discuss your idea/proposal in mailing list, 
please check [guide for a
 
 * Push your code change to your personal repo
 
-Now you can make changes to the code. Then you need to push it to 
**development_branch**:
+Now you can make changes to the code. Then you need to push it to your remote :
 
 ```shell
 # After making changes to the code ...
 git commit -m "KYLIN-0000 COMMIT SUMMARY"
-git push origin development_branch
+git push origin <development_branch>
 ```
 
-* Click the ___Compare & pull request___ button.
+* Click the ___Compare & pull request___ button in browser
 
 Once you push the changes to your repo, the Compare & pull request button will 
appear in GitHub.
 ![](images/how-to-contribute-02.png)
 
-* Click ___Create pull request___ to open a new pull request.
-
+* Fill the message and click ___Create pull request___ to open a new pull 
request.
 
 :::caution Before you create pull request
 1. Please add a detailed description in the `Proposed changes` of a pull 
request.
@@ -131,7 +145,6 @@ Once you push the changes to your repo, the Compare & pull 
request button will a
 
 ![](images/how-to-contribute-03.png)
 
-
 -----
 
 ## Guide for Reviewer
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 421a5e2228..92199b8478 100644
--- a/website/docs/development/how_to_debug_kylin_in_ide.md
+++ b/website/docs/development/how_to_debug_kylin_in_ide.md
@@ -16,33 +16,30 @@ last_update:
     author: Xiaoxiang Yu
 ---
 
-# How to debug Kylin in IDEA using docker
+## Debug Kylin in IDE with Hadoop
 
 ### 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 have to the following:
-
-- 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
+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.
 
 #### Deployment architecture
 Following is architecture of current deployment.
 
 ![debug_in_laptop](images/debug_kylin_by_docker_compose.png)
 
+This guide **assumes** you have prepared the following things:
+
+- [ ] A **laptop** with MacOS installed to do development work (Windows is not 
verified at the moment)
+- [ ] A **remote linux server** for testing and deployment purpose(if you do 
not prepare remote linux server, you will deploy Hadoop on your laptop)
+- [ ] kylin's source code is cloned into some directory in your laptop
+
 ### Prepare IDEA and build source code
 
-#### Software Requirement
+#### Step 1: Check Software Requirement
 
-Please visit [software_reqiurement](how_to_package#software_reqiurement).
+Please visit [software_requirement](how_to_package#software_reqiurement), make 
sure your laptop has meet the requirement.
 
-#### Build source code
+#### Step 2: Build source code
 - Build back-end source code before your start debug.
 ```shell
 cd <path-to-kylin-source>
@@ -50,55 +47,75 @@ mvn clean install -DskipTests
 ```
 
 - Build front-end source code. 
-(Please use node.js v12.14.0, for how to use specific version of node.js, 
please check [how to package](./how_to_package.md) )
+(Please use node.js **v12.14.0**, for how to use specific version of node.js, 
please check [how to switch to specific node 
js](how_to_package#install_older_node) )
 ```shell
 cd kystudio
 npm install
 ```
 
-#### Prepare IDEA configuration
-- Download spark and create running IDEA configuration for debug purpose.
-```shell
-./dev-support/sandbox/sandbox.sh init
-```
+#### Step 3: Install IntelliJ IDEA and build the source
+1. Install IDEA Community edition (Ultimate edition is ok too).
+2. Import the source code into IDEA. Click the **Open**, and choose the 
directory of **kylin source code**.
+  ![](images/OPEN_KYLIN_PROJECT.png)
+
+3. Install scala plugin and restart
+![](images/IDEA_Install_Scala_plugin.png)
+
+4. Configure SDK(JDK and Scala), make sure you use **JDK 1.8.X** and **Scala 
2.12.X**.
+![](images/IDEA_Notify_Install_SDK.png)
+
+5. Reload maven projects, and directory `scala` will be marked as source 
root(in blue color).
+![](images/IDEA_RELOAD_ALL_MAVEN_PROJECT.png)
 
-- Following is the shell output.
+6. Build the projects.(make sure you have executed `mvn clean package 
-DskipTests`, otherwise some source code is not generated by maven javacc 
plugin)
+   ![](images/PROJECT_BUILD_SUCCEED.png)
 
-![sandbox.sh init](images/how-to-debug-01.png)
+
+#### Step 4: Prepare IDEA configuration
+
+1. Download spark and create running IDEA configuration for debug purpose.
+  ```shell
+  ./dev-support/sandbox/sandbox.sh init
+  ```
+
+  Following is the shell output.
+  ![sandbox.sh init](images/IDEA_SANDBOX_INIT.png)
 
 ### 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`
+1. Install latest docker desktop in your laptop
+2. [**Optional**] Install docker engine on remote machine 
(https://docs.docker.com/engine/install/)
 
 :::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}
-```
+3. [**Optional**] If you want to deploy hadoop cluster on remote machine, 
please set correct `DOCKER_HOST`. 
 
-- Check available resource of your docker engine which you want to deploy 
Hadoop Cluster, make sure you leave 6 CPUs and 12 GB memory at least .
+  If you don't set `DOCKER_HOST`, you will deploy Hadoop Cluster in your 
laptop. (Make sure you can log in this server via SSH without input password 
each time by **ssh-copy-id**.)
+  ```shell
+  # see more detail at : 
https://docs.docker.com/compose/reference/envvars/#docker_host
+  export DOCKER_HOST=ssh://${USER}@${DOCKER_HOST}
+  ```
 
-Following is the setting page of Docker Desktop of MacBook.
+4. Check available resource of your docker desktop in laptop (or docker engine 
in remote server, depends on which machine you want to deploy Hadoop Cluster), 
make sure you leave 6 CPUs and 12 GB memory at least .
 
-![resources](images/docker-engine-resource.png)
+  Following is the setting page of Docker Desktop of MacBook.
 
-- Deploy hadoop cluster via docker compose on laptop(or on remote machine)
+  ![resources](images/docker-engine-resource.png)
 
-```shell
-./dev-support/sandbox/sandbox.sh up
-```
+5. Deploy hadoop cluster via docker compose on laptop(or on remote machine)
 
-![sandbox.sh up](images/how-to-debug-02.png)
+  ```shell
+  ./dev-support/sandbox/sandbox.sh up
+  ```
+
+  ![sandbox.sh up](images/how-to-debug-02.png)
 
 
 #### Check status of hadoop cluster
-- Wait 1-2 minutes, check health of hadoop, you can use following command to 
check status
+- Wait 2-5 minutes, check health of hadoop, you can use following command to 
check status
 
 ```shell
 ./dev-support/sandbox/sandbox.sh ps
@@ -128,11 +145,11 @@ Following output content shows all hadoop component are 
in health state.
 
 - Select "BootstrapServer[docker-sandbox]" on top of IDEA and click **Run** .
 
-![click BootstrapServer[docker-sandbox]](images/how-to-debug-05.png)
+![click BootstrapServer[docker-sandbox]](images/RUN_KYLIN_IN_IDEA.png)
 
 - Wait and check if Sparder is start succeed.
 
-![Spark is submitted](images/how-to-debug-06.png)
+![Spark is submitted](images/SPARDER_SUCCEED_IN_IDE.png)
 
 - Check if SparkUI of Sparder is started.
 
@@ -156,6 +173,8 @@ npm run devproxy
 
 ![setup front end](images/how-to-debug-09.png)
 
+- Create a new project, load table and create model
+
 - Validate Cube Build and Query function
 
 ![build job](images/local-build-succeed.png)
diff --git a/website/docs/development/how_to_package.md 
b/website/docs/development/how_to_package.md
index 0272dd7621..b8d29eb65e 100644
--- a/website/docs/development/how_to_package.md
+++ b/website/docs/development/how_to_package.md
@@ -23,7 +23,7 @@ last_update:
 |---------------| 
---------------------------------------------|----------------|--------------------|
 | 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))|
+| Node.js       |  Build front end                             | 12.14.0 is 
recommended ( or 12.x ~ 14.x) | [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:
@@ -90,18 +90,33 @@ For example, an unofficial package could be 
`apache-kylin-5.0.0-SNAPSHOT.2022081
 ./build/release/release.sh -P hadoop3
 ```
 
-### <span id="install_older_node">How to switch to older node.js</span>
+### <span id="install_older_node">How to install 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.
+1. Please visit https://nodejs.org/en/download/ to download and install the 
latest node.js . After installed, you may use follow command to verify if the 
latest node.js is in use:
+```shell
+$ node -v
+v16.17.0
+```
+
+2. Use some tools like https://github.com/nvm-sh/nvm to install specific 
version of node.js 
 
 ```shell
 ## Switch to specific version using nvm
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
 nvm install 12.14.0
 
-## Before packaging, please switch to specific version 
+## Before packaging, please switch to specific version
 nvm use 12.14.0
+```
 
+You may use follow command to verify if older node.js is in use:
+```shell
+$ node -v
+v12.14.0
+```
+
+3. Switch to latest node.js
+```shell
 ## switch to original version
 nvm use system
 ```
diff --git a/website/docs/development/how_to_write_doc.md 
b/website/docs/development/how_to_write_doc.md
index 21d223db4b..d2fe0e8840 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
 
 :::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.
+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-10 minutes.
 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).
 :::
 
@@ -135,16 +135,17 @@ DevelopmentSideBar: [
 
 
 #### Step 4: Preview in your local machine
-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:
+You can preview in your browser, please run following commands in the 
`website` directory, then access [doc of kylin in local](http://127.0.0.1:3000) 
in your browser:
 
 ```
 npm run start
 ```
 
-:::caution Checklist
+:::caution Check your doc
 - [ ] 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).
+- [ ] Whether the **link/pictures** works fine?
+- [ ] Whether the most important part was **highlighted**? You may [check this 
to highlight a paragraph](#highlight_paragraph).
+- [ ] Whether the **title level** follow [this guide](#heading_level)?
 :::
 
 #### Step 5: Create a pull request
@@ -230,6 +231,32 @@ doc5.0
 
 More details about structure which managed by Docusaurus, please refer to 
[Project structure 
rundown](https://docusaurus.io/docs/installation#project-structure-rundown).
 
+#### <span id="heading_level">Title/Heading Level</span>
+
+Here is [official guide about 
heading](https://docusaurus.io/docs/markdown-features/toc#markdown-headings).  
Please use level 3 title("###") and level 4 title("####") in most of the 
article.
+
+Following is a general guide:
+- Use level 2 heading(aka "##") as **top level** title. The number of top 
level title should not more than two. 
+- Use level 3 heading(aka "###") as **middle level** title. 
+- Use level 4 heading(aka "####") as **the lowest level** title.
+
+
+We recommend you to check for [this article](how_to_contribute) for example. 
Following is toc of it.
+```
+## Guide for Contributor
+### Detailed Description
+#### Step 1: Fork Apache Kylin Repo
+#### Step 2: Clone the fork repo
+#### Step 3: xxx
+#### Step 4: xxx
+...
+
+## Guide for Reviewer
+### Code Review Guideline
+### Patch +1 Policy
+...
+```
+
 #### Sidebar
 The Sidebar is managed by __sidebars.js__ , please refer to 
[Sidebar](https://docusaurus.io/docs/sidebar).
 
@@ -245,7 +272,7 @@ Using relative path for site links, check this [Markdown 
links](https://docusaur
 
 
 #### 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.
+We are using [Code 
Block](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:
diff --git a/website/docs/development/images/IDEA_Install_Scala_plugin.png 
b/website/docs/development/images/IDEA_Install_Scala_plugin.png
new file mode 100644
index 0000000000..4f76d76b48
Binary files /dev/null and 
b/website/docs/development/images/IDEA_Install_Scala_plugin.png differ
diff --git a/website/docs/development/images/IDEA_Notify_Install_SDK.png 
b/website/docs/development/images/IDEA_Notify_Install_SDK.png
new file mode 100644
index 0000000000..be07c15fdb
Binary files /dev/null and 
b/website/docs/development/images/IDEA_Notify_Install_SDK.png differ
diff --git a/website/docs/development/images/IDEA_RELOAD_ALL_MAVEN_PROJECT.png 
b/website/docs/development/images/IDEA_RELOAD_ALL_MAVEN_PROJECT.png
new file mode 100644
index 0000000000..1ec4a8b0da
Binary files /dev/null and 
b/website/docs/development/images/IDEA_RELOAD_ALL_MAVEN_PROJECT.png differ
diff --git a/website/docs/development/images/IDEA_SANDBOX_INIT.png 
b/website/docs/development/images/IDEA_SANDBOX_INIT.png
new file mode 100644
index 0000000000..5211499366
Binary files /dev/null and 
b/website/docs/development/images/IDEA_SANDBOX_INIT.png differ
diff --git a/website/docs/development/images/OPEN_KYLIN_PROJECT.png 
b/website/docs/development/images/OPEN_KYLIN_PROJECT.png
new file mode 100644
index 0000000000..fc77c2df70
Binary files /dev/null and 
b/website/docs/development/images/OPEN_KYLIN_PROJECT.png differ
diff --git a/website/docs/development/images/PROJECT_BUILD_SUCCEED.png 
b/website/docs/development/images/PROJECT_BUILD_SUCCEED.png
new file mode 100644
index 0000000000..6959d7f053
Binary files /dev/null and 
b/website/docs/development/images/PROJECT_BUILD_SUCCEED.png differ
diff --git a/website/docs/development/images/RUN_KYLIN_IN_IDEA.png 
b/website/docs/development/images/RUN_KYLIN_IN_IDEA.png
new file mode 100644
index 0000000000..b27be5fb26
Binary files /dev/null and 
b/website/docs/development/images/RUN_KYLIN_IN_IDEA.png differ
diff --git a/website/docs/development/images/SPARDER_SUCCEED_IN_IDE.png 
b/website/docs/development/images/SPARDER_SUCCEED_IN_IDE.png
new file mode 100644
index 0000000000..75cc3eaeb8
Binary files /dev/null and 
b/website/docs/development/images/SPARDER_SUCCEED_IN_IDE.png differ
diff --git a/website/docs/development/images/how-to-debug-05.png 
b/website/docs/development/images/how-to-debug-05.png
deleted file mode 100644
index 82fc6fbf22..0000000000
Binary files a/website/docs/development/images/how-to-debug-05.png and 
/dev/null differ
diff --git a/website/docs/development/images/how-to-debug-06.png 
b/website/docs/development/images/how-to-debug-06.png
deleted file mode 100644
index 3a0fa27433..0000000000
Binary files a/website/docs/development/images/how-to-debug-06.png and 
/dev/null differ
diff --git a/website/sidebars.js b/website/sidebars.js
index 20d7ebea2a..922dd4badc 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -850,6 +850,10 @@ const sidebars = {
                     type: 'doc',
                     id: 'development/how_to_release'
                 },
+                {
+                    type: 'doc',
+                    id: 'development/how_to_subscribe_mailing_list'
+                },
 
             ],
         },

Reply via email to