如何贡献

Apache Kylin 一直寻求的不只是代码的贡献,还寻求使用文档,性能报告,问答等方面的贡献。所有类型的贡献都为成为 Kylin Committer 铺平了道路。每个人都有机会,尤其是那些有分析和解决方案背景的,因为缺少来自于用户和解决方案视角的内容。

源分支

代码和文档都在 Git 源代码控制之下。注意不同分支的用途。

  • master: 新功能的主开发分支
  • 2.[n].x: 一些主要版本的维护分支
  • document: 文档分支

组件及拥有者

Apache Kylin 有几个子组件。为了更好地帮助社区的发展,我们为每个组件安排了一个或多个组件负责人。

  • 组件负责人是志愿者(组件领域的专家)。负责人需要成为 Apache Kylin 提交者或 PMC。

  • 负责人将尝试审查其组件范围内的补丁。

  • 负责人可以根据他的愿望和社区需求进行轮换。

  • 在提名或投票新提交者时,提名者需要说明候选人可以成为哪个组件的负责人。

  • 如果您已经是 Apache Kylin 提交者或 PMC 成员并希望成为组件负责人的志愿者,请给 dev 列表写信,我们将为您注册。

  • 所有项目计划,决策仍由 Apache Kylin PMC 管理。

  • 如果您认为组件列表需要更新(添加,删除,重命名等),请给 dev 列表写信,我们将对其进行审核。

组件负责人列在了这个 Apache Kylin JIRA components page 页面中的 Description 字段位置。负责人列在“Description”字段中而不是“Component Lead”字段中,因为后者仅允许我们列出一个人,然而其鼓励组件具有多个负责人。

选择一个任务

这里有新创建的任务等待被完成,由 JIRA 追踪。为了让其容易被搜索,这里有一些过滤条件。

  • 由李扬管理的任务列表
  • 由 Ted Yu 创建的任务列表,重要的小的 bugs 且其中一些很容易被修复。
  • 您也可以在 Kylin JIRA 中搜索标签 “newbie”。

在做大任务之前别忘了在邮箱列表中讨论。

如果为 bug 或功能创建了新的 JIRA,请记住为社区提供足够的信息:

  • 问题或功能的良好摘要
  • 详细说明,可能包括:
    • 这个问题发生的环境
    • 重现问题的步骤
    • 错误跟踪或日志文件(作为附件)
    • model 或 cube 的元数据
  • 相关组件:我们将根据此选择安排审核人员。
  • 受影响的版本:您正在使用的 Kylin 版本。

进行代码更改

  • 搭建开发环境
  • 提出 JIRA,描述功能/提升/bug
  • 在邮件列表或 issue 评论中与其他人讨论,确保提议的更改符合其他人正在做的事情以及为项目规划的内容
  • 在您的 fork 中进行修改
    • 目前没有严格的代码样式,但一般规则与现有文件保持一致。例如,对 java 文件使用 4 空格缩进。
    • 尽可能为代码更改添加测试用例。
    • 确保“mvn clean package”和“mvn test”能够获得成功。
    • 充分的单元测试和集成测试是代码更改的必要部分。
  • 运行测试 以确保您的更改质量良好且不会破坏任何内容。如果您的补丁生成不正确或您的代码不符合代码指南,则可能会要求您重做某些工作。
  • 生成补丁并将其附加到相关的 JIRA。

生成 Patch

  • 使用 submit-patch.py(推荐)创建 patches,上传到 jira 并可选择在 Review Board 上创建/更新评论。 Patch 名称自动格式化为(JIRA).(分支名称).(补丁号).patch,遵循 Yetus 的命名规则。
  1. $ ./dev-support/submit-patch.py -jid KYLIN-xxxxx -b master -srb
  • 用 -h 标志可以了解此脚本的详细用法信息。最有用的选项是:
    • -b BRANCH, –branch BRANCH : 指定用于生成 diff 的基本分支。如果未指定,则使用跟踪分支。如果没有跟踪分支,则会抛出错误。
    • -jid JIRA_ID, –jira-id JIRA_ID : 如果使用,则从 jira 中的附件推断下一个补丁版本并上传新补丁。脚本将要求 jira 用户名/密码进行身份验证。如果未设置,则将补丁命名为 .patch。
  • 默认情况下,它还会创建/更新 review board。要跳过该操作,请使用 -srb 选项。它使用 jira 中的“Issue Links”来确定审核请求是否已存在。如果没有审核请求,则创建一个新请求并使用 jira 摘要,patch 说明等填充所有必填字段。此外,还将此评论的链接添加到 jira。
  • 安装需要的 python 依赖,从 master 分支执行 pip install -r dev-support/python-requirements.txt

  • 或者,您也可以手动生成 patch。请首先使用 git rebase -i,将较小的提交组合(squash)为一个较大的提交。然后使用 git format-patch 命令生成 patch,有关详细指南,请参阅如何使用 Git 创建和应用补丁

代码审查

审核人员需要从以下角度审核 patch:

  • 功能性:patch 必须解决问题,并在提交审核之前已经过贡献者的验证。
  • 测试范围:更改必须由 UT 或集成测试覆盖,否则无法维护。执行案例包括 GUI,shell 脚本等。
  • 性能:改变不应该降低 Kylin 的性能。
  • 元数据兼容性:更改应支持旧元数据定义。否则,需要元数据迁移工具和文档。
  • API 兼容性:更改不应该破坏公共 API 的功能和行为;如果需要用新 API 替换旧 API,请在那里打印警告消息。
  • 文档:如果需要同时更新 Kylin 文档,请创建另一个 JIRA,并将“Document”作为要跟踪的组件。在 JIRA 文档中,附加“文档”分支的文档更改 patch。

不符合上述规则的补丁可能无法合并。

Patch +1 政策

在提交之前,适合单个组件范围的修补程序至少需要一个组件负责人的 +1。如果负责人不在 — 在忙或其他 — 两个非负责人(即两个提交者)的 +1,就足够了。

跨组件的 patch 在提交之前至少需要两个 +1s,最好由 x-component patch 涉及的组件负责人的 +1。

任何人都可以在 patch 上 -1,任何 -1 都可以否决补丁;在解决 -1 的理由之前,它不能被提交。

应用 Patch

  • Committer 将审核 JIRA 中的 Pull Requests 和 Patches 的正确性,性能,设计,编码风格,测试覆盖率
  • 必要时进行讨论和修改;
  • committer 将代码合并到目标分支中
    • 对于 git patch,请使用“git am -s -3 patch-file”命令进行应用;
    • 如果是来自 github Pull Request,则需要添加“This closing#”作为提交消息的一部分。这将允许 ASF Git bot 关闭 PR。
    • 使用 git rebase 确保合并结果是提交的简化。

进行文档更改

查看如何写文档.