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 01:21:01 UTC
[kylin] branch doc5.0 updated: KYLIN-5236 add how_to_contribute.md
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 01b62836b5 KYLIN-5236 add how_to_contribute.md
01b62836b5 is described below
commit 01b62836b53c63765e2b33d071f9248743f7b75e
Author: Mukvin <bo...@163.com>
AuthorDate: Wed Aug 24 14:49:01 2022 +0800
KYLIN-5236 add how_to_contribute.md
---
website/docs/development/how_to_contribute.md | 138 ++++++++++++++++++++-
.../development/images/how-to-contribute-01.png | Bin 0 -> 15722 bytes
.../development/images/how-to-contribute-02.png | Bin 0 -> 29070 bytes
.../development/images/how-to-contribute-03.png | Bin 0 -> 142664 bytes
.../development/images/how-to-write-doc-02.png | Bin 0 -> 92873 bytes
5 files changed, 134 insertions(+), 4 deletions(-)
diff --git a/website/docs/development/how_to_contribute.md b/website/docs/development/how_to_contribute.md
index 3822834d97..192306fa42 100644
--- a/website/docs/development/how_to_contribute.md
+++ b/website/docs/development/how_to_contribute.md
@@ -1,8 +1,138 @@
---
-sidebar_position: 1
+title: How to contribute
+language: en
+sidebar_label: How to contribute
+pagination_label: How to contribute
+toc_min_heading_level: 2
+toc_max_heading_level: 6
+pagination_prev: null
+pagination_next: null
+keywords:
+ - contribute
+draft: false
+last_update:
+ date: 08/24/2022
---
-# How to contribute
+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.
-1. JIRA Issue
-2. Github
+
+## 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
+
+* `main`: Maintenance branch for a certain major release for v4.x
+* `2.[n].x`: Maintenance branch for a certain major release for v2.x
+* `3.[n].x`: Maintenance branch for a certain major release for v3.x
+* `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.
+
+Do not forget to discuss in [mailing list](#TODO) before working on a big task.
+
+If 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
+ - the steps to reproduce the problem
+ - the error trace or log files (as attachment)
+ - the metadata of the model or cube
+* Related components: we will arrange reviewer based on this selection.
+* Affected version: which Kylin you're using.
+
+## Making Code Changes
+* [Setup development environment](how_to_debug_kylin_in_ide.md)
+* Raise a JIRA, describe the feature/enhancement/bug
+* Discuss with others in mailing list or issue comments, make sure the proposed changes fit in with what others are doing and have planned for the project
+* Make changes in your fork
+ * 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 "mvn clean package" and "mvn test" can get success.
+ * Sufficient unit test and integration test is a mandatory part of code change.
+* [Run tests](how_to_test.md) to ensure your change is in good quality and does not break anything. If your patch was generated incorrectly or your code does not adhere to the code guidelines, you may be asked to redo some work.
+* Generate a patch and attach it to relative JIRA.
+
+## Create a pull request
+
+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).
+
+* Fork [Apache Kylin Repo](https://github.com/apache/kylin) to your repository.
+
+
+
+* Clone the fork repo to your local system.
+
+```shell
+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:
+
+```shell
+git checkout -b new_branch
+```
+
+2. Create a new remote for the upstream repo with the command:
+
+```shell
+git remote add upstream https://github.com/apache/kylin.git
+```
+> In this case, "upstream repo" refers to the original repo which is [Apache Kylin Repo](https://github.com/apache/kylin.git).
+
+Now you can make changes to the code. The following code creates a new branch, makes an arbitrary change, and pushes it to **new_branch**:
+
+```shell
+# After making changes to the code ...
+git commit -m "Modify some code to new_branch"
+git push origin new_branch
+```
+
+* Click the ___Compare & pull request___ button.
+
+Once you push the changes to your repo, the Compare & pull request button will appear in GitHub.
+
+
+* Click ___Create pull request___ to open a new pull request.
+
+
+
+> Note:
+>
+> 1. Please add a detailed description in the `Proposed changes` of a pull request.
+>
+> 2. Click the `Types of changes` that you have made.
+>
+> 3. Check the `Checklist`.
+
+## Code Review
+The reviewer needs to review the patch from the following perspectives:
+
+* _Functionality_: the patch MUST address the issue and has been verified by the contributor before submitting for review.
+* _Test coverage_: the change MUST be covered by a UT or the Integration test, otherwise it is not maintainable. Execptional case includes GUI, shell script, etc.
+* _Performance_: the change SHOULD NOT downgrade Kylin's performance.
+* _Metadata compatibility_: the change should support old metadata definition. Otherwise, a metadata migration tool and documentation is required.
+* _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.
+
+A patch which doesn't comply with the above rules may not get merged.
+
+## Patch +1 Policy
+
+Patches that fit within the scope of a single component require, at least, a +1 by one of the component’s owners before commit. If owners are absent — busy or otherwise — two +1s by non-owners but committers will suffice.
+
+Patches that span components need at least two +1s before they can be committed, preferably +1s by owners of components touched by the x-component patch.
+
+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).
diff --git a/website/docs/development/images/how-to-contribute-01.png b/website/docs/development/images/how-to-contribute-01.png
new file mode 100644
index 0000000000..fc88c077ba
Binary files /dev/null and b/website/docs/development/images/how-to-contribute-01.png differ
diff --git a/website/docs/development/images/how-to-contribute-02.png b/website/docs/development/images/how-to-contribute-02.png
new file mode 100644
index 0000000000..898b9f8179
Binary files /dev/null and b/website/docs/development/images/how-to-contribute-02.png differ
diff --git a/website/docs/development/images/how-to-contribute-03.png b/website/docs/development/images/how-to-contribute-03.png
new file mode 100644
index 0000000000..0419abddf2
Binary files /dev/null and b/website/docs/development/images/how-to-contribute-03.png differ
diff --git a/website/docs/development/images/how-to-write-doc-02.png b/website/docs/development/images/how-to-write-doc-02.png
new file mode 100644
index 0000000000..cbe1c71647
Binary files /dev/null and b/website/docs/development/images/how-to-write-doc-02.png differ