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:26 UTC
[kylin] 02/02: Add how to subscribe 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 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