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 <[email protected]> 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', },
