如何贡献 Kylin

Apache Kylin 始终在寻找各种贡献，不仅包括代码，还包括文档、测试、性能报告 、发布管理、团队协调、成功参考等。所有这些都为迈向 Apache Committer 铺平了道路。 特别是，我们期待从业务和分析角度来看的内容，例如分析最佳实践和成功生产场景。技术只有在对现实世界产生影响时才有用。这些内容对刚进入社区的用户非常有帮助，但往往被技术开发人员忽视。

User story wanted

如果您想贡献业务或分析内容，请参阅 如何编写的文档。

源码分支

代码和文档都处于Git源代码管理之下。注意不同分支的目的。

分支	类型	描述
kylin5	开发分支	活跃的 v5.x 开发分支
doc5.0	文档分支	v5.x 文档分支
main	维护分支	v4.x 维护分支
kylin3	维护分支	v3.x 维护分支
document	文档分支	v4.x 及更早版本的文档分支

---

贡献者指南

如何协作?

与所有 ASF 项目一样，Apache Kylin 遵循How the ASF works在世界各地进行分布式协作。

对于新人，请阅读 Project Management and collaboration 和 Roles，快速了解基础知识。

代码贡献

简介之后是分步详细说明。

1. 设置开发环境
2. 选择或创建新的 JIRA 任务
3. 社区胜过代码! 与他人讨论您的更改计划
4. 更改代码并创建拉取请求
5. 代码评审人评审代码
6. 进行相关文档更改 如何编写文档.

Step 1. 设置开发环境

使用 Windows 开发

对于对于使用 Windows 开发，在 Windows Subsystem for Linux 中设置Kylin开发环境是最佳选择。 请遵循 how to install WSL with GUI ，了解如何安装带有图形界面的WSL， 并在 WSL 中下载 Kylin 代码和安装您最喜欢的 IDE 以获得最佳性能。

1. 访问 https://github.com/apache/kylin 并点击 Fork 按钮。

2. 克隆 forked repo 到本地

   cd /path/you/prefer
   git clone https://github.com/<YourUserName>/kylin.git 

3. 创建一个开发分支

   base_branch 取决于您的计划要修复的 Kylin 版本，请查看 源码分支.

   ## 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>

   例如，如果我想修复 Kylin 5.0.0-Alpha 的一些问题，您可以执行以下命令：

   git checkout kylin5
   git checkout -b fix_some_issue

   为了更好地了解 Git 操作，请查看 Contributing to a Project.

4. 阅读更多关于开发环境设置的更多信息，请参阅 如何设置 IDE .

Step 2. 选择或创建新的 JIRA 任务

与其他的 ASF 项目一样，我们使用 JIRA 来跟踪开发任务。

提交安全漏洞

对于可能存在的漏洞，请不要使用JIRA，因为公开该信息可能会立即伤害现有用户。请 遵循 report possible vulnerability 进行提交

如果您想为异常或功能创建新的JIRA，请记住为社区提供足够的信息：

• 精确而紧凑的 摘要
  • 例如: 在 构建全局字典 步骤中读取大文件 /dict/xxx 失败
• 准确的 issue 类型
  • New Feature , 如果您想开发新功能
  • Improvement , 如果您想改进现有功能
  • Bug , 如果您发现某些东西没有按预期工作
  • Wish , 如果您希望其他人提供新功能
• 受影响版本: 受影响 Kylin 的版本
• 详细的 描述，可能包括：
  • 发生此问题的环境，OS/Hadoop/Spark版本 ...
  • 复现问题的步骤
  • 线程堆栈信息, 异常堆栈或日志文件（作为附件上传）
  • 模型或者 cube 元数据（作为附件上传）
  • 如果可能的话，进行问题原因分析，例如: 分析问题原因示例
• 如果您计划解决该问题，请将任务 分配 给您。

JIRA 示例:

Step 3. 与他人讨论您的更改计划

时刻牢记, 社区胜过代码!

在开始编码之前，请务必与社区讨论您的想法、计划和设计。如果没有社区的参与，这仅仅是你的一个个人项目。

与社区合作有以下好处：

• 知识比代码更重要。如果没有人掌握维护代码的知识，代码就会失效。与社区合作可以传承知识，保持开源的活力。
• 对于重大变更，调整架构和高层设计至关重要。否则，在以后提交代码时，您可能会面临问题甚至在提交代码时甚至被拒绝。
• 你可能会找到想做或已经在做同样事情的志愿者。有了更多的帮手，通常会带来更好的代码质量、更好的测试和更好的文档。

在 ASF ，通常在 邮件列表 进行社区讨论。

• 如果尚未订阅过 Apache Kylin 邮件列表，请阅读如何订阅邮件列表。
  • 注意: 确认邮件 可能会在垃圾箱中。
• 有关电子邮件讨论的建议和示例
  • 如何更好的提问
  • 优秀示例: 关于邮件讨论.

Step 4. 更改代码并创建拉取请求

关于修改代码的一些注意事项：

• 虽然目前没有严格的代码风格，但一般规则是与现有文件保持一致。例如: 使用 4 空格 Java 文件缩进。
• 为你的代码更改添加测试用例是必须的。
• 在创建拉取请求之前，确保所有测试通过，这将确保您的更改质量和不影响其他功能
• 由于你的代码将被评审，请提前阅读代码审查指南。追求更好的设计原则。

如果代码更改完成，您可以在新的拉取请求中提交更改：

• 将代码更改推入开发分支

  # After making changes to the code ...
  git commit -m "KYLIN-XXXX COMMIT SUMMARY"
  git push <your_fork> <development_branch>

• 在GitHub中，点击 Compare & pull request 按钮来发起一个新的拉取请求。

  

• Kylin 社区要求填写一个拉取请求模板。填写信息后，点击 Create pull request 来创建一个新的拉取请求

  Kylin 拉取请求模板

  交流内容，而不仅仅是代码。

  1. 在 Proposed changes 中，描述变更的 why 和 how 。
  2. 选择正确的 Types of changes 并检查 Checklist。
  3. 再次检查目标分支是否正确，否则代码无法合入。

  

Step 5. 代码评审

Kylin committer 会接收到通知，并按照代码评审指南审查你的拉取请求。您可能会通过拉取请求或 JIRA 评论联系，如果涉及到讨论可能会是会议邀请。

审查正在进行中，请耐心等待。大多数 committer 都有自己的工作，只能在业余时间为社区服务。如果你想加快流程，试着在拉取请求中添加评论。

当所有这些都完成后，您的拉取请求将被 committer 合并到目标分支中。

Step 6. 进行相关文档更改

如果你想让别人了解一个新特性或者一个重要的 bug 已经被解决了，那么文档和代码一样重要。 社区胜过代码！

请按照 如何编写文档 为每个较大的新特性或者重要的 bug 更改编写文档。 一定要在代码PR中提到文档更改，这样审阅者就知道您遵循了最佳实践。

---

评审人指南

代码评审指南

评审人需要从以下几个方面对代码进行审查：

• Functionality: 补丁 必须 解决问题，并且在提交审查之前已被贡献者验证。
• Test coverage: 变更 必须 由单元测试或集成测试覆盖，否则它是不可维护的。异常案例包括GUI、shell脚本等。
• Performance: 改变 不应该 降低 Kylin 的性能。
• Metadata compatibility: 更改应该支持旧的元数据定义。否则，需要元数据迁移工具和文档。
• API compatibility: 更改 不应该 坏公共 API 的功能和行为；如果需要用新的 API 替换旧的 API ，则需要打印警告消息。
• Documentation: 如果 Kylin 文档需要一起更新，创建另一个文档 JIRA 。在文档 JIRA 中，附加针对 “document” 分支的文档更改补丁。

必须遵守规则

不符合上述规则的补丁可能不会被合并。

补丁+1策略

在提交之前，单个模块范围的补丁至少需要模块所有者之一的人的 +1。 如果所有者缺席(忙或其他), 将需要两个非所有者的 +1 或者 committer 的 +1。

跨越模块的补丁在提交之前至少需要两个 +1，最好是模块补丁所涉及的模块的所有者 +1。

任何人在一个补丁上的任何 -1 都会否决了这个补丁；在解决 -1 的理由之前，不能合并它。