贡献指南

我们欢迎贡献者帮助改进 AutoBangumi，更好地解决用户遇到的问题。

本指南将引导您了解如何向 AutoBangumi 贡献代码。请在提交 Pull Request 之前花几分钟阅读。

本文涵盖：

• 项目路线图
  • 征求意见稿 (RFC)
• Git 分支管理
  • 版本号规则
  • 分支开发，主干发布
  • 分支生命周期
  • Git 工作流程概述
• Pull Request
• 发布流程

项目路线图

AutoBangumi 开发团队使用 GitHub Project 看板来管理计划中的开发、正在进行的修复及其进度。

这可以帮助您了解：

• 开发团队正在做什么
• 哪些内容与您想要的贡献一致，以便您直接参与
• 哪些工作已经在进行中，避免重复工作

在 Project 中，除了常见的 [Feature Request]、[BUG] 和小改进外，您还会看到 [RFC] 条目。

征求意见稿 (RFC)

通过 issues 中的 RFC 标签查找现有的 AutoBangumi RFC。

对于小改进或 bug 修复，可以直接调整代码并提交 Pull Request。只需阅读分支管理部分以确保基于正确的分支进行工作，以及 Pull Request 部分了解 PR 如何被合并。

对于涉及范围较广的较大功能重构，请首先通过 Issue: Feature Proposal 编写 RFC 提案，简要描述您的方法并寻求开发者讨论和共识。

某些提案可能与开发团队已经做出的决定冲突，此步骤有助于避免浪费精力。

如果您只是想讨论是否添加或改进某个功能（而不是"如何实现"），请使用 -> Issue: Feature Request

RFC 提案是**"在功能/重构的具体开发之前，供开发者审查技术设计/方法的文档"**。

其目的是确保协作的开发者清楚地知道"要做什么"和"如何完成"，所有开发者都可以参与公开讨论。

这有助于评估影响（被忽略的考虑因素、向后兼容性、与现有功能的冲突）。

因此，提案重点描述解决问题的方法、设计和步骤。

Git 分支管理

版本号规则

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。在所有分支中查找它们。

分支生命周期

当一个 Minor 开发分支（如 3.1-dev）完成功能开发并首次合并到 main 时：

• 发布 Minor 版本（如 3.1.0）
• 创建下一个 Minor 开发分支（3.2-dev）用于下个版本的功能
  • 上一个版本的分支（3.0-dev）将被归档
• 当前 Minor 分支（3.1-dev）进入维护期——不再添加新功能/重构，只修复 bug
  • Bug 修复先合并到维护分支，然后合并到 main 进行 Patch 发布

对于选择 Git 分支的贡献者：

• Bug 修复 — 基于当前已发布版本的 Minor 分支，向该分支提交 PR
• 新功能/重构 — 基于下一个未发布版本的 Minor 分支，向该分支提交 PR

"当前已发布版本"是 [Releases 页面] 上的最新版本

Git 工作流程概述

提交时间线从左到右 --->

Pull Request

请确保按照上述 Git 分支管理部分选择正确的 PR 目标分支：

• Bug 修复 → 向当前已发布版本的 Minor 维护分支提交 PR
• 新功能/重构 → 向下一版本的 Minor 开发分支提交 PR

• 一个 PR 应该对应单一关注点，不要引入无关的更改。

  将不同的关注点拆分为多个 PR，以帮助团队在每次审查中专注于一个问题。

• 在 PR 标题和描述中，简要说明更改内容，包括原因和意图。

  在 PR 描述中链接相关的 issues 或 RFC。

  这有助于团队在代码审查时快速了解上下文。

• 确保勾选"允许维护者编辑"。这允许直接进行小的编辑/重构，节省时间。

• 确保本地测试和代码检查通过。这些也会在 PR CI 中检查。

  • 对于 bug 修复和新功能，团队可能会要求相应的单元测试覆盖。

开发团队将尽快审查贡献者的 PR，进行讨论或批准合并。

发布流程

发布只由维护者手动推送版本标签触发，合并 PR 本身不会发布。

• beta：在开发分支上打 X.Y.Z-beta.N 形式的标签（如 4.0.0-beta.1）。CI 构建 Docker 镜像，镜像标签为该版本号与 dev-latest，并创建预发布的 GitHub Release。
• 正式版：开发分支经 PR 合并到 main 后，在 main 的合并提交上打 X.Y.Z 形式的标签。CI 校验标签格式，并确认该提交在 main 上，然后构建镜像（标签为版本号与 latest），创建 GitHub Release，发布说明取自 docs/changelog/<X.Y>.md。

每个 Release 的附件包括 WebUI、在线更新包、插件 SDK 轮子与插件开发 skill（见 获取 SDK）。

Bug 修复 PR 通常会快速发布，一般在一周内。

新功能发布需要更长时间，时间不太可预测。查看 GitHub Project 看板了解开发进度——当所有计划功能完成时发布版本。