| # 如何参与项目贡献 |
| |
| > 更多信息可以见官网[如何参与项目贡献](https://linkis.apache.org/community/how-to-contribute) |
| |
| 非常感谢贡献 Linkis 项目!在参与贡献之前,请仔细阅读以下指引。 |
| |
| ## 一、贡献范畴 |
| |
| ### 1.1 Bug 反馈与修复 |
| |
| 我们建议无论是 Bug 反馈还是修复,都先创建一个 Issue 来仔细描述 Bug 的状况,以助于社区可以通过 Issue 记录来找到和回顾问题以及代码。Bug 反馈 Issue 通常需要包含**完整描述 Bug 的信息**以及**可复现的场景**,这样社区才能快速定位导致 Bug 的原因并修复它。包含 `#bug` 标签的打开的 Issue 都是需要被修复的。 |
| |
| ### 1.2 功能交流、实现、重构 |
| |
| 在交流过程中,详细描述新功能(或重构)的细节、机制和使用场景,能够促使它更好更快地被实现(包括测试用例和代码,及 CI/CD 相关工作)。**如果计划实现一个重大的功能(或重构),请务必通过 Issue 或其他方式与核心开发团队进行沟通**,这样大家能以最效率的方式来推进它。包含 `#feature` 标签的打开的 Issue 都是需要被实现的新功能,包含 `#enhancement` 标签打开的 Issue 都是需要改进重构的功能。 |
| |
| ### 1.3 Issue 答疑 |
| |
| 帮助回答 Issue 中的使用问题是为 Linkis 社区做贡献的一个非常有价值的方式;社区中总会有新用户不断进来,在帮助新用户的同时,也可以展现您的专业知识。 |
| |
| ### 1.4 文档改进 |
| |
| Linkis 文档位于[Linkis 官网](https://linkis.apache.org/zh-CN/docs/latest/introduction/) ,文档的补充完善对于 Linkis 的发展也至关重要。 |
| |
| ### 1.5 其他 |
| |
| 包括参与和帮助组织社区交流、社区运营活动等,其他能够帮助 Linkis 项目和社区的活动。 |
| |
| ## 二、贡献流程 |
| |
| ### 2.1 分支结构 |
| |
| Linkis 源码可能会产生一些临时分支,但真正有明确意义的只有以下三个分支: |
| |
| - master: 最近一次稳定 release 的源码,偶尔会多几次 hotfix 提交; |
| - release-*: 稳定的 release 版本; |
| - dev-*: 主要开发分支; |
| |
| #### 2.1.1 概念 |
| |
| - Upstream 仓库:<https://github.com/apache/linkis> linkis 的 apache 仓库文中称为 Upstream 仓库 |
| - Fork 仓库: 从 <https://github.com/apache/linkis> fork 到自己个人仓库 称为 Fork 仓库 |
| |
| #### 2.1.2 同步 Upstream 仓库分支最新代码到自己的 Fork 仓库 |
| |
| - step1 进入用户项目页面,选中要更新的分支 |
| - step2 点击 code 下载按钮下方的 Fetch upstream,选择 Fetch and merge (如自己的 Fork 仓库 该分支不小心污染了,可以删除该分支后,同步 Upstream 仓库新分支到自己的 Fork 仓库 ,参见指引[同步 Upstream 仓库分支最新代码到自己的 Fork 仓库 ](#213-同步 Upstream 仓库新分支到自己的 Fork 仓库 )) |
|  |
| |
| #### 2.1.3 同步 Upstream 仓库新分支到自己的 Fork 仓库 |
| |
| 场景:Upstream 仓库有新增分支,但是 fork 的库没有该分支 (可以选择删除后,重新 fork,但是会丢失未 merge 到原始仓库的变更) |
| |
| 在自己 clone 的本地项目中操作 |
| |
| - step1 添加 apacheUpstream 仓库镜像到本地 |
| |
| ```shell script |
| git remote add apache git@github.com:apache/linkis.git |
| ``` |
| |
| - step2 拉去 apache 镜像信息到本地 |
| |
| ```shell script |
| git fetch apache |
| ``` |
| |
| - step3 根据需要同步的新分支来创建本地分支 |
| |
| ```shell script |
| git checkout -b dev-1.1.4 apache/dev-1.1.4 |
| ``` |
| |
| - step4 把本地分支 push 到自己的仓库,如果自己的仓库没有 dev-1.1.4 分支,则会创建 dev-1.1.4 分支 |
| |
| ```shell script |
| git push origin dev-1.1.4:dev-1.1.4 |
| ``` |
| |
| - step5 删除 upstream 的分支 |
| |
| ```shell script |
| git remote remove apache |
| ``` |
| |
| - step6 更新分支 |
| |
| ```shell script |
| git pull |
| ``` |
| |
| #### 2.1.4 一个 pr 的流程 |
| |
| - step1 确认当前开发的基础分支(一般是当前进行的中版本,如当前社区开发中的版本 1.1.0,那么分支就是 dev-1.1.0,不确定的话可以在社区群里问下或则在 issue 中@相关同学) |
| |
| - step2 同步 Upstream 仓库分支最新代码到自己的 Fork 仓库 分支,参见指引 [2.1.2 同步 Upstream 仓库分支最新代码到自己的 Fork 仓库 ] |
| |
| - step3 基于开发分支,拉取新 fix/feature 分支 (不要直接在原分支上修改,如果后续 pr 以 squash 方式 merge 后,提交的 commit 记录会被合并成一个) |
| |
| ```shell script |
| git checkout -b dev-1.1.4-fix dev-1.1.4 |
| git push origin dev-1.1.4-fix:dev-1.1.4-fix |
| ``` |
| |
| - step4 进行开发 |
| - step5 提交 pr(如果是正在进行中,开发还未完全结束,请在 pr 标题上加上 WIP 标识 如 `[WIP] Dev 1.1.1 Add junit test code for [linkis-common]` ;关联对应的 issue 等) |
| - step6 等待被合并 |
| - step7 删除 fix/future 分支 (可以在 github 页面上进行操作) |
| |
| ```shell script |
| git branch -d dev-1.1.4-fix |
| git push |
| ``` |
| |
| 请注意:大特性的 dev 分支,在命名时除了版本号,还会加上相应的命名说明,如:dev-0.10.0-flink,指 0.10.0 的 flink 特性开发分支。 |
| |
| ### 2.2 开发指引 |
| |
| Linkis 前后端代码共用同一个代码库,但在开发上是分离的。在着手开发之前,请先将 Linkis 项目 fork 一份到自己的 Github Repositories 中, 开发时请基于自己 Github Repositories 中的 Linkis 代码库进行开发。 |
| |
| 我们建议克隆 dev 分支命名为 dev-fix 来开发,同时在自己仓库新建 dev-fix 分支,直接在原分支上修改,如果后续 pr 以 squash 方式 merge 后,提交的 commit 记录会被合并成一个 |
| |
| ```shell script |
| #拉取分支 |
| git clone https://github.com/{githubid}/linkis.git --branch dev |
| #根据 dev 生成本地 dev-fix 分支 |
| git checkout -b dev-fix dev |
| #把本地 dev-fix 分支推到自己的仓库 |
| git push origin dev-fix dev-fix |
| ``` |
| |
| ### 2.3 Issue 提交指引 |
| |
| - 如果您还不知道怎样向开源项目发起 PR,请参考[About issues](https://docs.github.com/en/github/managing-your-work-on-github/about-issues) |
| - Issue 名称,应一句话简单描述您的问题或建议;为了项目的国际化推广,请用英文,或中英文双语书写 issue |
| - 每个 Issue,请至少带上 component 和 type 两个 label,如 component=Computation Governance/EngineConn,type=Improvement.参考:[issue #590](https://github.com/apache/linkis/issues/590) |
| |
| ### 2.4 Pull Request(PR) 提交指引 |
| |
| - 如果您还不知道怎样向开源项目发起 PR,请参考[About pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) |
| - 无论是 Bug 修复,还是新功能开发,请将 PR 提交到 dev-* 分支 |
| |
| - PR 和提交名称遵循 `<type>(<scope>): <subject>` 原则,详情可以参考[Commit message 和 Change log 编写指南](https://linkis.apache.org/zh-CN/docs/latest/development/development-specification/commit-message) |
| - 如果 PR 中包含新功能,理应将文档更新包含在本次 PR 中 |
| - 如果本次 PR 尚未准备好合并,请在名称头部加上 [WIP] 前缀(WIP = work-in-progress) |
| - 所有提交到 dev-* 分支的提交至少需要经过一次 Review 才可以被合并 |
| |
| ### 2.5 Review 标准 |
| |
| 在贡献代码之前,可以了解一下什么样的提交在 Review 中是受欢迎的。简单来说,如果一项提交能带来尽可能多增益和尽可能少的副作用或风险,那它被合并的几率就越高,Review 的速度也会越快。风险大、价值低地提交是几乎不可能被合并的,并且有可能会被拒绝 Review。 |
| |
| #### 2.5.1 增益 |
| |
| - 修复导致 Bug 的主要原因 |
| - 添加或修复一个大量用户亟需的功能或问题 |
| - 简单有效 |
| - 容易测试,有测试用例 |
| - 减少复杂度以及代码量 |
| - 经社区讨论过的、确定需要改进的问题 |
| |
| #### 2.5.2 副作用和风险 |
| |
| - 仅仅修复 Bug 的表面现象 |
| - 引入复杂度高的新功能 |
| - 为满足小众需求添加复杂度 |
| - 改动稳定的现有 API 或语义 |
| - 导致其他功能不能正常运行 |
| - 添加大量依赖 |
| - 随意改变依赖版本 |
| - 一次性提交大量代码或改动 |
| |
| #### 2.5.3 Reviewer 注意事项 |
| |
| - 请使用建设性语气撰写评论 |
| - 如果需要提交者进行修改,请明确说明完成此次 Pull Request 所需要修改的所有内容 |
| - 如果某次 PR 在合并后发现带来了新问题,Reviewer 需要向 PR 作者联系并沟通解决问题;如果无法联系到 PR 作者,Reviewer 需要将此次 PR 进行还原 |
| |
| --- |
| |
| ## 三、贡献进阶 |
| |
| ### 3.1 关于 Committers(Collaborators) |
| |
| #### 3.1.1 如何成为 Committer |
| |
| 如果您对 Linkis 提过颇具价值的 PR 并且被合并,或是连续贡献超过半年,且至少主导过一次版本的发布,您可以通过官方微信群找到 Linkis 项目的一个 PMC ,如果他愿意提名您为 committer,并愿意为您陈述您的贡献给所有 PMC 和 Committer,那么接下来会发起一次投票;PMC 和其他 Committers 将会一起投票决定是否允许您的加入,如果得到足够票数,您将成为 Linkis 项目的 Committer。 |
| |
| #### 3.1.2 Committer 的权利 |
| |
| - 可以加入官方开发者微信群,参与讨论和制定 Linkis 开发计划 |
| - 可以对 Issue 进行管理,包括关闭、添加标签 |
| - 可以创建和管理项目分支,master、dev-* 分支除外 |
| - 可以对提交到 dev-* 分支的 PR 进行 Review |
| - 可以申请成为 Committee 成员 |
| |
| ### 3.2 关于 Committee |
| |
| #### 3.2.1 如何成为 Committee 成员 |
| |
| 如果您是 Linkis 项目的 Committer,并且您贡献的所有内容得到了其他 Committee 成员的认可,您可以申请成为 Linkis Committee 成员,其他 Committee 成员将会一起投票决定是否允许您的加入,如果全票通过,您将成为 Linkis Committee 成员。 |
| |
| #### 3.2.2 Committee 成员的权利 |
| |
| - 可以合并其他 Committers 和贡献者提交到 dev-** 分支的 PR |
| - 可以参与决定 Linkis 项目的 roadmap 和发展方向 |
| - 可以参与新版本发布 |