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/08/25 07:19:11 UTC
[kylin] branch doc5.0 updated (01b62836b5 -> eb80fb2c9d)
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 01b62836b5 KYLIN-5236 add how_to_contribute.md
new 13787c5e5b Refine some pages including how to add new doc, how to contribute
new eb80fb2c9d Add roadmap.md
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 | 16 +-
website/docs/development/how_to_package.md | 6 +-
website/docs/development/how_to_release.md | 4 +-
website/docs/development/how_to_test.md | 6 +-
website/docs/development/how_to_write_doc.md | 228 ++++++++++-----------
.../development/images/how-to-write-doc-01.png | Bin 2043 -> 176990 bytes
website/docs/development/roadmap.md | 23 +++
7 files changed, 155 insertions(+), 128 deletions(-)
[kylin] 01/02: Refine some pages including how to add new doc, how to contribute
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 13787c5e5b9ac3c740b0151c847c5a68dccc01ba
Author: XiaoxiangYu <xx...@apache.org>
AuthorDate: Thu Aug 25 14:25:35 2022 +0800
Refine some pages including how to add new doc, how to contribute
---
website/docs/development/how_to_contribute.md | 16 +-
website/docs/development/how_to_package.md | 6 +-
website/docs/development/how_to_write_doc.md | 228 ++++++++++-----------
.../development/images/how-to-write-doc-01.png | Bin 2043 -> 176990 bytes
4 files changed, 124 insertions(+), 126 deletions(-)
diff --git a/website/docs/development/how_to_contribute.md b/website/docs/development/how_to_contribute.md
index 192306fa42..1b9a6097e8 100644
--- a/website/docs/development/how_to_contribute.md
+++ b/website/docs/development/how_to_contribute.md
@@ -20,8 +20,8 @@ Apache Kylin is always looking for contributions of not only code, but also usag
## Source Branches
Both code and document are under Git source control. Note the purpose of different branches.
-* `kylin5`: Development branch for a certain major release for v5.x
-* `doc5.0`: Document branch for V5.x
+* `kylin5`: Development branch for v5.x
+* `doc5.0`: Document branch for v5.x
* `main`: Maintenance branch for a certain major release for v4.x
* `2.[n].x`: Maintenance branch for a certain major release for v2.x
@@ -29,11 +29,7 @@ Both code and document are under Git source control. Note the purpose of differe
* `document`: Document branch for V4.x and before
## Pick a task
-There are open tasks waiting to be done, tracked by JIRA. To make it easier to search, there are a few JIRA filters.
-
-* [A list of tasks](https://issues.apache.org/jira/issues/?filter=12339895) managed by Yang Li.
-* [A list of tasks](https://issues.apache.org/jira/issues/?filter=12341496) opened by Ted Yu, important small bugs and some are easy fixes.
-* Also you can search for tag "newbie" in Kylin JIRA.
+There are open tasks waiting to be done, tracked by JIRA.
Do not forget to discuss in [mailing list](#TODO) before working on a big task.
@@ -76,13 +72,13 @@ git clone https://github.com/<YourUserName>/kylin.git
Once the repo is cloned, you need to do two things:
-1. Create a new branch by issuing the command:
+* Create a new branch by issuing the command:
```shell
git checkout -b new_branch
```
-2. Create a new remote for the upstream repo with the command:
+* Create a new remote for the upstream repo with the command:
```shell
git remote add upstream https://github.com/apache/kylin.git
@@ -135,4 +131,4 @@ Patches that span components need at least two +1s before they can be committed,
Any -1 on a patch by anyone vetoes a patch; it cannot be committed until the justification for the -1 is addressed.
## Making Document Changes
-Check out [How to Write Document](how_to_write_doc.md).
+Check out [How to Write Document](./how_to_write_doc).
diff --git a/website/docs/development/how_to_package.md b/website/docs/development/how_to_package.md
index a52c95a8c0..dd3f86a186 100644
--- a/website/docs/development/how_to_package.md
+++ b/website/docs/development/how_to_package.md
@@ -64,7 +64,7 @@ For example, an unofficial package could be `apache-kylin-5.0.0-SNAPSHOT.2022081
# and third party cannot be distributed because of apache distribution policy(size and license)
./build/release/release.sh -noSpark -official
-## Case 3: A package for runing on Apache Hadoop 3 platform
+## Case 3: A package for Apache Hadoop 3 platform
./build/release/release.sh -P hadoop3
```
@@ -73,9 +73,11 @@ For example, an unofficial package could be `apache-kylin-5.0.0-SNAPSHOT.2022081
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.
```shell
-## switch to specific version
+## 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
nvm use 12.14.0
## switch to original version
diff --git a/website/docs/development/how_to_write_doc.md b/website/docs/development/how_to_write_doc.md
index 4cc53b45f9..7e4ceaf698 100644
--- a/website/docs/development/how_to_write_doc.md
+++ b/website/docs/development/how_to_write_doc.md
@@ -15,13 +15,11 @@ last_update:
date: 08/24/2022
---
-We write documents in MD format and convert to HTML using [Docusaurus](https://docusaurus.io/). [Docusaurus](https://docusaurus.io/) is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/main/packages).
+From Kylin 5.0, Kylin community proposed to write documents using [Docusaurus](https://docusaurus.io/). Please note multi-version and i18n(multi-language) is in our plan, so it is not supported right now.
-The [Docusaurus](https://docusaurus.io/) generated HTML gets uploaded to apache SVN and becomes Kylin website. All MD source files are managed in git so all changes and contributors are clearly tracked.
+### Shortcut: Edit a single existent page
-## Quick edit a page
-
-If you found some minor typos or mistakes on a page, you can quickly fix the page and create a commit.
+If you found some minor typos or mistakes on a single page, you can quickly commit the change without clone source code and preview in user's local machine.
Just scroll down the page to the bottom and click the `Edit this page`.
@@ -30,19 +28,19 @@ Just scroll down the page to the bottom and click the `Edit this page`.
Edit the page.
-Create a commit.
+Raise a pull request.
-> Note: If you want to add documentation or some more changes, please do as following steps.
+> Note: If you want to add NEW pages/upload images/change frontend style, please do as following steps.
## Before your work
-Before you add or edit documentation, please deploy the document compilation environment.
+Before you add new documentation, please deploy the document compilation environment.
There are two steps:
- [Deploy a local document compilation environment](#Deploy)
-- [Download docs repo and configuration](#Download)
+- [Download repo](#Download)
### <span id="Deploy">Deploy a local document compilation environment</span>
@@ -57,7 +55,7 @@ Install following tools before you add or edit documentation:
2. And optionally any markdown editor you prefer
-### <span id="Download">Download docs repo and initialization</span>
+### <span id="Download">Download docs repo</span>
1. Download the doc repo to any path you prefer.
@@ -69,27 +67,120 @@ git clone --branch doc5.0 https://github.com/apache/kylin.git # Or git clone -b
2. After pre-step, install dependencies for prerequisite of doc.
```shell
-cd /path/to/repo/website
+cd website
npm install
```
-To check that initialization occurred successfully, run:
+To check if that environment works well, run:
```shell
npm run start
```
-then, a local website of `http://localhost:3000` will automatically open in your default browser and no errors occurred.
+then, home page doc (`http://localhost:3000`) will automatically open in your default browser and no errors occurred.
-## About [Docusaurus](https://docusaurus.io/)
+
+## How to create new document
+
+### Create a new markdown file
+
+Open doc with any markdown editor, draft content as following:
+
+```
+---
+title: Example doc
+language: en
+sidebar_label: Example doc
+pagination_label: Example doc
+toc_min_heading_level: 2
+toc_max_heading_level: 6
+pagination_prev: null
+pagination_next: null
+keywords:
+ - doc
+draft: false
+last_update:
+ date: 08/23/2022
+---
+
+## This is example doc
+The quick brown fox jump over the lazy dog.
+```
+
+> ***Note***:
+>
+> 1. Please note that every doc need the ___Head metadata___. More details about `Head metadata` of a doc, please refer to [Head metadata](https://docusaurus.io/docs/markdown-features/head-metadata).
+>
+> 2. Please use the template `Head metadata` in your modified doc.
+ ```shell
+ ---
+ title: Example doc
+ language: en
+ sidebar_label: Example doc
+ pagination_label: Example doc
+ toc_min_heading_level: 2
+ toc_max_heading_level: 6
+ pagination_prev: null
+ pagination_next: null
+ keywords:
+ - doc
+ draft: false
+ last_update:
+ date: 08/23/2022
+ ---
+ ```
+>
+> 3. Please use `second heading level` for the doc header start.
+
+
+### How to add a new page to the sidebar
+
+Add the `{}` doc side block in sideBars.
+
+Example:
+
+Scene: If you want to add the sidebar of `how_to_write_doc.md` to be the children menu of `development`.
+
+Then, modify the `DevelopmentSideBar` block in sidebars.js and add a new block in the `items` of `DevelopmentSideBar`.
+
+```shell
+DevelopmentSideBar: [
+ {
+ ...
+ items: [
+ {...},
+ ...,
+ {
+ type: 'doc',
+ id: 'development/how_to_write_doc.md'
+ },
+ ],
+ },
+],
+```
+
+
+### 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:
+
+```
+npm run start
+```
+Then access http://127.0.0.1:3000 in your browser.
+
+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
+
+### About [Docusaurus](https://docusaurus.io/)
[Docusaurus](https://docusaurus.io/) is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).
Apache Kylin's website and documentation is using [Docusaurus](https://docusaurus.io/) to manage and generate final content which avaliable at [http://kylin.apache.org](http://kylin.apache.org).
-## Kylin document structure and navigation menu
+### 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.
@@ -159,7 +250,7 @@ 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
+### Navigation menu
The menu is managed by Docusaurus collection:
@@ -167,112 +258,21 @@ The menu is managed by Docusaurus collection:
More details about sidebars in Docusaurus, please refer to [Sidebar](https://docusaurus.io/docs/sidebar).
-## How to add a doc to the sidebar
-
-Add the `{}` doc side block in sideBars.
-
-Example:
-Scene: If you want to add the sidebar of `how_to_write_doc.md` to be the children menu of `development`.
+### How to add image
+All image should be put under _images_ folder, in your document, please using below sample to include image:
-Then, modify the `DevelopmentSideBar` block in sidebars.js and add a new block in the `items` of `DevelopmentSideBar`.
-
-```shell
-DevelopmentSideBar: [
- {
- ...
- items: [
- {...},
- ...,
- {
- type: 'doc',
- id: 'development/how_to_write_doc.md'
- },
- ],
- },
-],
```
-
-
-## How to edit document
-Open doc with any markdown editor, draft content and preview in local.
-
-Sample Doc:
-
+
```
----
-title: Example doc
-language: en
-sidebar_label: Example doc
-pagination_label: Example doc
-toc_min_heading_level: 2
-toc_max_heading_level: 6
-pagination_prev: null
-pagination_next: null
-keywords:
- - doc
-draft: false
-last_update:
- date: 08/23/2022
----
-## This is example doc
-The quick brown fox jump over the lazy dog.
-```
-
-> ***Note***:
->
-> 1. Please note that every doc need the ___Head metadata___. More details about `Head metadata` of a doc, please refer to [Head metadata](https://docusaurus.io/docs/markdown-features/head-metadata).
->
-> 2. Please use the template `Head metadata` in your modified doc.
- ```shell
- ---
- title: Example doc
- language: en
- sidebar_label: Example doc
- pagination_label: Example doc
- toc_min_heading_level: 2
- toc_max_heading_level: 6
- pagination_prev: null
- pagination_next: null
- keywords:
- - doc
- draft: false
- last_update:
- date: 08/23/2022
- ---
- ```
->
-> 3. Please use `second heading level` for the doc header start.
-
-
-
-## How to add image
-All impage please put under _images_ folder, in your document, please using below sample to include image:
-
-```
-
-```
-
-## How to add link
+### How to link to another page
Using relative path for site links, for example:
```
-[How To Write Docs](../development/how_to_write_doc.md).
-```
-
-## How to add code highlight
-We are using [Rouge](https://github.com/jneen/rouge) to highlight code syntax.
-check this doc's source code for more detail sample.
-
-
-## How to preview in your local
-You can preview in your markdown editor, to check exactly what it will looks like on website, please run Docusaurus in the root of repo folder:
-
-```
-npm run start
+[How To Write Docs](../development/how_to_write_doc).
```
-Then access http://127.0.0.1:3000 in your browser.
-If everything is normal, create a pull request to [Apache Kylin Repo](https://github.com/apache/kylin) and target branch is `doc5.0`.
+### How to add code highlight
+We are using [Rouge](https://github.com/jneen/rouge) to highlight code syntax, check this doc for more detail sample.
diff --git a/website/docs/development/images/how-to-write-doc-01.png b/website/docs/development/images/how-to-write-doc-01.png
index 227d6ccf88..3ea171bb23 100644
Binary files a/website/docs/development/images/how-to-write-doc-01.png and b/website/docs/development/images/how-to-write-doc-01.png differ
[kylin] 02/02: Add roadmap.md
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 eb80fb2c9d5a0c116c2365ee34129a615ce8fd8c
Author: XiaoxiangYu <xx...@apache.org>
AuthorDate: Thu Aug 25 15:18:05 2022 +0800
Add roadmap.md
---
website/docs/development/how_to_release.md | 4 +++-
website/docs/development/how_to_test.md | 6 +++++-
website/docs/development/roadmap.md | 23 +++++++++++++++++++++++
3 files changed, 31 insertions(+), 2 deletions(-)
diff --git a/website/docs/development/how_to_release.md b/website/docs/development/how_to_release.md
index ddb0438605..bb285d9b54 100644
--- a/website/docs/development/how_to_release.md
+++ b/website/docs/development/how_to_release.md
@@ -2,4 +2,6 @@
sidebar_position: 1
---
-# How to release
\ No newline at end of file
+# How to release
+
+to be continued
\ No newline at end of file
diff --git a/website/docs/development/how_to_test.md b/website/docs/development/how_to_test.md
index 4d07fd24e9..6f7cdcfa1c 100644
--- a/website/docs/development/how_to_test.md
+++ b/website/docs/development/how_to_test.md
@@ -2,4 +2,8 @@
sidebar_position: 1
---
-# How to test
\ No newline at end of file
+# How to test
+
+```shell
+sh dev-support/unit_testing.sh
+```
\ No newline at end of file
diff --git a/website/docs/development/roadmap.md b/website/docs/development/roadmap.md
index fff02a3a92..0fd4a253e7 100644
--- a/website/docs/development/roadmap.md
+++ b/website/docs/development/roadmap.md
@@ -3,3 +3,26 @@ sidebar_position: 1
---
# Roadmap
+
+### Kylin 5.0.0-alpha & Kylin 5.0.0
+
+- Re-design metadata schema to support new feature
+ - Merge DataModel and CubeDesc into new DataModel
+ - Add IndexPlan to support flexible index management
+ - Add IndexEntity to support different index type
+ - Add LayoutEntity to support different storage layout of same Index
+ - Add DataFlow/ComputedColumnDesc etc
+- New metadata cache synchronization via AuditLog
+- Rewrite model engine and build engine to implement some important new features:
+ - Support schema change
+ - Add Computed Column to support light-weight ETL
+ - Add Table Index to support raw query(non-aggregation query)
+- Rewrite whole WEB UI
+ - Use Vue.js, a brand new front-end framework, to replace AngularJS
+ - Simplify modeling process into one canvas
+- Integrated with native compute engine preliminarily
+- SCD2, async query, cost-based index optimizer etc
+
+### Kylin 5.1.0
+
+- Support deploy Kylin on K8S with micro-service architecture