diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 8305fdcf..b1ef3ae1 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -158,11 +158,20 @@ export default defineConfig({ link: "/changelog/3.0", }, { - text: "2.6 更新日志", + text: "2.6 更新说明", link: "/changelog/2.6", }, ], }, + { + text: "开发者文档", + items: [ + { + text: "贡献指南", + link: "/dev/", + }, + ] + } ], }, }); diff --git a/docs/deploy/windows.md b/docs/deploy/windows.md index af374788..3d77a288 100644 --- a/docs/deploy/windows.md +++ b/docs/deploy/windows.md @@ -8,29 +8,21 @@ cd Auto_Bangumi ``` -2. 修改 `backend\src\module\api\web.py` 以允许 `DEV_VERSION` 下仍然可以显示 Web UI： +2. 创建版本信息文件： ```powershell - ((Get-Content -path .\src\module\api\web.py -Raw) -replace 'if VERSION != "DEV_VERSION":','if True:') | Set-Content -Path .\src\module\api\web.py + echo "VERSION='local'" > backend\src\__version__.py ``` -3. 创建一个新的分支，以方便后续更新时与远程 `main` 分支合并： - - ```powershell - git checkout -b non-docker-deployment - git commit -a -m "Enable WebUI for dev version" - ``` - -4. 新建 `python` 虚拟环境、激活并安装依赖（需保证 `python -V` 打印的版本符合 `Dockerfile` 中的要求，如 `FROM python:3.11-alpine AS APP`） +3. 新建 `python` 虚拟环境、激活并安装依赖（需保证 `python -V` 打印的版本符合 `Dockerfile` 中的要求，如 `FROM python:3.11-alpine AS APP`） ```powershell python -m venv env .\env\Scripts\Activate.ps1 - python -m pip install -r requirements.txt + python -m pip install -r backend\requirements.txt ``` - -5. 下载 WebUI 并安装： +4. 下载 WebUI 并安装： ```powershell Invoke-WebRequest -Uri "https://github.com/Rewrite0/Auto_Bangumi_WebUI/releases/latest/download/dist.zip" -OutFile "dist.zip" @@ -38,7 +30,7 @@ mv dist\* backend\src\templates ``` -6. 创建 `data` 与 `config` 目录和空白的 `config_dev.json`（如果有必要将这些目录存储在其他位置，建议使用 Junction Directory 链接即可） +5. 创建 `data` 与 `config` 目录和空白的 `config_dev.json`（如果有必要将这些目录存储在其他位置，建议使用 Junction Directory 链接即可） ```powershell mkdir backend\src\data @@ -47,14 +39,14 @@ ``` 默认情况下，PowerShell 输出文件编码为 `UTF-16LE`，你需要将 `config_dev.json` 的编码格式改为 `UTF-8`。 -7. 运行程序测试是否配置正确： +6. 运行程序测试是否配置正确： ```powershell cd backend\src python main.py ``` -8. 接下来配置成服务以实现开机自启，以下以 `nssm` 为例： +7. 接下来配置成服务以实现开机自启，以下以 `nssm` 为例： ```powershell nssm install AutoBangumi (Get-Command python).Source @@ -63,7 +55,7 @@ nssm set AutoBangumi Start SERVICE_DELAYED_AUTO_START ``` -9. [可选] 由于 3.0 版本之前 AutoBangumi 没有修改规则或者批量移动下载位置的功能，可能遇到季名不符合需要 (如《鬼灭之刃 刀匠村篇》被视作一个仅具有一季的独立的影视作品，而不是系列动画的第三季) 或者中途想继续下载但是移出库防止出现在新剧集通知中等情况，可与考虑将下载目录和库目录区分开并用 Junction Directory 相连，这样在管理库时可以随意移动软链接而不影响 AutoBangumi 的工作。比如： +8. [可选] 由于 3.0 版本之前 AutoBangumi 没有修改规则或者批量移动下载位置的功能，可能遇到季名不符合需要 (如《鬼灭之刃 刀匠村篇》被视作一个仅具有一季的独立的影视作品，而不是系列动画的第三季) 或者中途想继续下载但是移出库防止出现在新剧集通知中等情况，可与考虑将下载目录和库目录区分开并用 Junction Directory 相连，这样在管理库时可以随意移动软链接而不影响 AutoBangumi 的工作。比如： ```powershell ### Configurations $downloadDir = "path\to\download_dir" diff --git a/docs/dev/index.md b/docs/dev/index.md new file mode 100644 index 00000000..9573c71d --- /dev/null +++ b/docs/dev/index.md @@ -0,0 +1,138 @@ +# 贡献指南 Contributing + +我们欢迎各位 Contributors 参与贡献帮助 AutoBangumi 更好的解决大家遇到的问题， + +这篇指南会指导你如何为 AutoBangumi 贡献功能修复代码，可以在你要提出 Pull Request 之前花几分钟来阅读一遍这篇指南。 + +这篇文章包含什么？ + +- [项目规划 Roadmap](#项目规划-roadmap) + - [提案寻求共识 Request for Comments](#提案寻求共识-request-for-comments) +- [分支管理 Git Branch](#分支管理-git-branch) + - [版本号](#版本号) + - [分支开发，主干发布](#分支开发主干发布) + - [Branch 生命周期](#branch-生命周期) + - [Git Workflow 一览](#git-workflow-一览) +- [Pull Request](#pull-request) +- [版本发布介绍](#版本发布介绍) + + +## 项目规划 Roadmap + +AutoBangumi 开发组使用 [GitHub Project](https://github.com/EstrellaXD/Auto_Bangumi/projects?query=is%3Aopen) 看板来管理预计开发的规划、在修复中的问题，以及它们处理的进度； + +这将帮助你更好的了解 +- 开发团队在做什么？ +- 有什么和你想贡献的方向一致的，可以直接参与实现与优化 +- 有什么已经在进行中的，避免自己重复不必要的工作 + +在 [Project](https://github.com/EstrellaXD/Auto_Bangumi/projects?query=is%3Aopen) 中你可以看到除通常的 `[Feature Request]`, `[BUG]`, 一些小优化项以外，还有一类 **`[RFC]`**； + +### 提案寻求共识 Request for Comments + +> 在 issue 中通过 `RFC` label 能找到到现有的 [AutoBangumi RFCs](https://github.com/EstrellaXD/Auto_Bangumi/issues?q=is%3Aissue+label%3ARFC) + +对于一些小的优化项或者 bug 修复，你大可以直接帮忙调整代码然后提出 Pull Request，只需要简单阅读下 [分支管理](#分支管理-Git-Branch) 章节以基于正确的版本分支修复、以及通过 [Pull Request](#Pull-Request) 章节了解 PR 将如何被合并。 + +
+ +而如果你打算做的是一项**较大的**功能重构，改动范围大而涉及的方面比较多，那么希望你能通过 [Issue: 功能提案](https://github.com/EstrellaXD/Auto_Bangumi/issues/new?assignees=&labels=RFC&projects=&template=rfc.yml&title=%5BRFC%5D%3A+) 先写一份 RFC 提案来简单阐述「你打算怎么做」的简短方案，来寻求开发者的讨论和共识。 + +因为有些方案可能是开发团队原本讨论并且认为不要做的事，而上一步可以避免你浪费大量精力。 + +> 如果仅希望讨论是否添加或改进某功能本身，而非「要如何实现」，请使用 -> [Issue: 功能改进](https://github.com/EstrellaXD/Auto_Bangumi/issues/new?labels=feature+request&template=feature_request.yml&title=%5BFeature+Request%5D+) + + +
+ +一份 [提案(RFC)](https://github.com/EstrellaXD/Auto_Bangumi/issues?q=is%3Aissue+is%3Aopen+label%3ARFC) 定位为 **「在某功能/重构的具体开发前，用于开发者间 review 技术设计/方案的文档」**， + +目的是让协作的开发者间清晰的知道「要做什么」和「具体会怎么做」，以及所有的开发者都能公开透明的参与讨论； + +以便评估和讨论产生的影响 (遗漏的考虑、向后兼容性、与现有功能的冲突)， + +因此提案侧重在对解决问题的 **方案、设计、步骤** 的描述上。 + + +## 分支管理 Git Branch + +### 版本号 + +AutoBangumi 项目中的 Git 分支使用与发布版本规则密切相关，因此先介绍版本规范； + +AutoBangumi 发布的版本号遵循 [「语义化版本 SemVer」](https://semver.org/lang/zh-CN/) 的规范， + +使用 `..` 三位版本的格式，每一位版本上的数字更新含义如下： + +- **Major**: 大版本更新，很可能有不兼容的 配置/API 修改 +- **Minor**: 向下兼容的功能性新增 +- **Patch**: 向下兼容的 Bug 修复 / 小优化修正 + +### 分支开发，主干发布 + +AutoBangumi 项目使用「分支开发，主干发布」的模式， + +[**`main`**](https://github.com/EstrellaXD/Auto_Bangumi/commits/main) 分支是稳定版本的 **「主干分支」**，只用于发布版本，不用于直接开发新功能或修复。 + +每一个 Minor 版本都有一个对应的 **「开发分支」** 用于开发新功能、与发布后维护修复问题， + +开发分支的名字为 `.-dev`，如 `3.1-dev`, `3.0-dev`, `2.6-dev`， 你可以在仓库的 [All Branches 中搜索到它们](https://github.com/EstrellaXD/Auto_Bangumi/branches/all?query=-dev)。 + + +### 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 页面]](https://github.com/EstrellaXD/Auto_Bangumi/releases) 最新版本，这也与 [[GitHub Container Registry]](https://github.com/EstrellaXD/Auto_Bangumi/pkgs/container/auto_bangumi) 中最新版本相同 + + +### Git Workflow 一览 + +> 图中 commit timeline 从左到右 ---> + +![dev-branch](../image/dev/branch.png) + + +## 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](https://github.com/EstrellaXD/Auto_Bangumi/projects?query=is%3Aopen) 看板中看到开发进度，一个版本规划的新功能都开发完备后就会发版。 + diff --git a/docs/image/dev/branch.png b/docs/image/dev/branch.png new file mode 100644 index 00000000..b45bd46f Binary files /dev/null and b/docs/image/dev/branch.png differ