Skip to content

Latest commit

 

History

History
190 lines (115 loc) · 8.35 KB

CONTRIBUTING.md

File metadata and controls

190 lines (115 loc) · 8.35 KB

贡献指南 Contributing

我们欢迎各位 Contributors 参与贡献帮助 AutoBangumi 更好的解决大家遇到的问题,

这篇指南会指导你如何为 AutoBangumi 贡献功能修复代码,可以在你要提出 Pull Request 之前花几分钟来阅读一遍这篇指南。

这篇文章包含什么?

项目规划 Roadmap

AutoBangumi 开发组使用 GitHub Project 看板来管理预计开发的规划、在修复中的问题,以及它们处理的进度;

这将帮助你更好的了解

  • 开发团队在做什么?
  • 有什么和你想贡献的方向一致的,可以直接参与实现与优化
  • 有什么已经在进行中的,避免自己重复不必要的工作

Project 中你可以看到除通常的 [Feature Request], [BUG], 一些小优化项以外,还有一类 [RFC]

提案寻求共识 Request for Comments

在 issue 中通过 RFC label 能找到到现有的 AutoBangumi RFCs

对于一些小的优化项或者 bug 修复,你大可以直接帮忙调整代码然后提出 Pull Request,只需要简单阅读下 分支管理 章节以基于正确的版本分支修复、以及通过 Pull Request 章节了解 PR 将如何被合并。


而如果你打算做的是一项较大的功能重构,改动范围大而涉及的方面比较多,那么希望你能通过 Issue: 功能提案 先写一份 RFC 提案来简单阐述「你打算怎么做」的简短方案,来寻求开发者的讨论和共识。

因为有些方案可能是开发团队原本讨论并且认为不要做的事,而上一步可以避免你浪费大量精力。

如果仅希望讨论是否添加或改进某功能本身,而非「要如何实现」,请使用 -> Issue: 功能改进


一份 提案(RFC) 定位为 「在某功能/重构的具体开发前,用于开发者间 review 技术设计/方案的文档」

目的是让协作的开发者间清晰的知道「要做什么」和「具体会怎么做」,以及所有的开发者都能公开透明的参与讨论;

以便评估和讨论产生的影响 (遗漏的考虑、向后兼容性、与现有功能的冲突),

因此提案侧重在对解决问题的 方案、设计、步骤 的描述上。

分支管理 Git Branch

版本号

AutoBangumi 项目中的 Git 分支使用与发布版本规则密切相关,因此先介绍版本规范;

AutoBangumi 发布的版本号遵循 「语义化版本 SemVer」 的规范,

使用 <Major>.<Minor>.<Patch> 三位版本的格式,每一位版本上的数字更新含义如下:

  • Major: 大版本更新,很可能有不兼容的 配置/API 修改
  • Minor: 向下兼容的功能性新增
  • Patch: 向下兼容的 Bug 修复 / 小优化修正

分支开发,主干发布

AutoBangumi 项目使用「分支开发,主干发布」的模式,

main 分支是稳定版本的 「主干分支」,只用于发布版本,不用于直接开发新功能或修复。

每一个 Minor 版本都有一个对应的 「开发分支」 用于开发新功能、与发布后维护修复问题,

开发分支的名字为 <Major>.<Minor>-dev,如 3.1-dev, 3.0-dev, 2.6-dev, 你可以在仓库的 All Branches 中搜索到它们

Branch 生命周期

当一个 Minor 开发分支(以 3.1-dev 为例) 完成新功能开发,首次合入 main 分支后,

  • 发布 Minor 版本 (如 3.1.0)
  • 同时拉出下一个 Minor 开发分支(3.2-dev),用于下一个版本新功能开发
    • 上一个版本开发分支(3.0-dev)进入归档不再维护
  • 且这个 Minor 分支(3.1-dev)进入维护阶段,不再增加新功能/重构,只维护 Bugs 修复
    • Bug 修复到维护阶段的 Minor 分支(3.1-dev)后,会再往 main 分支合并,并发布 Patch 版本

根据这个流程,对于各位 Contributors 在开发贡献时选择 Git Branch 来说,则是:

  • 若「修复 Bug」,则基于当前发布版本的 Minor 分支开发修复,并 PR 到这个分支
  • 若「添加新功能/重构」,则基于还未发布的下一个版本 Minor 分支开发,并 PR 到这个分支

「当前发布版本」为 [Releases 页面] 最新版本,这也与 [GitHub Container Registry] 中最新版本相同

Git Workflow 一览

图中 commit timeline 从左到右 --->

%%{init: {'theme': 'base', 'gitGraph': {'showCommitLabel': true}}}%%

gitGraph:
  checkout main
  commit id: "."
  branch 3.0-dev
  commit id: "feat 1"
  commit id: "feat 2"
  commit id: "feat 3"

  checkout main
  merge 3.0-dev tag: "3.0.9"
  commit id: ".."

  branch 3.1-dev
  commit id: "feat 4"

  checkout 3.0-dev
  commit id: "PR merge (fix)"
  checkout main
  merge 3.0-dev tag: "3.0.10"

  checkout 3.1-dev
  commit id: "feat 5"
  commit id: "feat 6"

  checkout main
  merge 3.1-dev tag: "3.1.0"
  commit id: "..."

  branch 3.2-dev
  commit id: "feat 7"
  commit id: "feat 8"

  checkout 3.1-dev
  commit id: "PR merge (fix) "
  checkout main
  merge 3.1-dev tag: "3.1.1"

  checkout 3.2-dev
  commit id: "PR merge (feat)"
Loading

Pull Request

请确保你根据上文的 Git 分支管理 章节选择了正确的 PR 目标分支,

  • 若「修复 Bug」,则 PR 到当前发布版本的 Minor 维护分支
  • 若「添加新功能/重构」,则 PR 下一个版本 Minor 开发分支

  • 一个 PR 应该只对应一件事,而不应引入不相关的更改;

    对于不同的事情可以拆分提多个 PR,这能帮助开发组每次 review 只专注一个问题。

  • 在提 PR 的标题与描述中,最好对修改内容做简短的说明,包括原因和意图,

    如果有相关的 issue 或 RFC,应该把它们链接到 PR 描述中,

    这将帮助开发组 code review 时能最快了解上下文。

  • 确保勾选了「允许维护者编辑」(Allow edits from maintainers) 选项。这使我们可以直接进行较小的编辑/重构并节省大量时间。

  • 请确保本地通过了「单元测试」和「代码风格 Lint」,这也会在 PR 的 GitHub CI 上检查

    • 对于 bug fix 和新功能,通常开发组也会请求你添加对应改动的单元测试覆盖

开发组会在有时间的最快阶段 Review 贡献者提的 PR 并讨论或批准合并(Approve Merge)。

版本发布介绍

版本发布目前由开发组通过手动合并「特定发版 PR」后自动触发打包与发布。

通常 Bug 修复的 PR 合并后会很快发版,通常不到一周;

而新功能的发版时间则会更长而且不定,你可以在我们的 GitHub Project 看板中看到开发进度,一个版本规划的新功能都开发完备后就会发版。

贡献文档

如果要为文档做贡献,请注意以下几点:

  • 更新分支为 docs-update,并基于它做修改.
  • 请确保你的 PR 标题和描述中包含了你的修改的目的和意图。

撰写文档请尽量使用规范的书面化用语,遵照 Markdown 语法,以及 中文文案排版指北 中的规范。