mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-04-04 19:19:29 +08:00
Merge remote-tracking branch 'origin/docs-update' into docs-update
This commit is contained in:
EstrellaXD
@@ -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/",
|
||||
},
|
||||
]
|
||||
}
|
||||
],
|
||||
},
|
||||
});
|
||||
|
||||
@@ -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"
|
||||
|
||||
138
docs/dev/index.md
Normal file
138
docs/dev/index.md
Normal file
@@ -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 将如何被合并。
|
||||
|
||||
<br/>
|
||||
|
||||
而如果你打算做的是一项**较大的**功能重构，改动范围大而涉及的方面比较多，那么希望你能通过 [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+)
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
一份 [提案(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>.<Minor>.<Patch>` 三位版本的格式，每一位版本上的数字更新含义如下：
|
||||
|
||||
- **Major**: 大版本更新，很可能有不兼容的 配置/API 修改
|
||||
- **Minor**: 向下兼容的功能性新增
|
||||
- **Patch**: 向下兼容的 Bug 修复 / 小优化修正
|
||||
|
||||
### 分支开发，主干发布
|
||||
|
||||
AutoBangumi 项目使用「分支开发，主干发布」的模式，
|
||||
|
||||
[**`main`**](https://github.com/EstrellaXD/Auto_Bangumi/commits/main) 分支是稳定版本的 **「主干分支」**，只用于发布版本，不用于直接开发新功能或修复。
|
||||
|
||||
每一个 Minor 版本都有一个对应的 **「开发分支」** 用于开发新功能、与发布后维护修复问题，
|
||||
|
||||
开发分支的名字为 `<Major>.<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 从左到右 --->
|
||||
|
||||
|
||||
|
||||
|
||||
## Pull Request
|
||||
|
||||
请确保你根据上文的 Git 分支管理 章节选择了正确的 PR 目标分支，
|
||||
> - 若「修复 Bug」，则 PR 到**当前发布版本**的 Minor 维护分支
|
||||
> - 若「添加新功能/重构」，则 PR **下一个版本** Minor 开发分支
|
||||
|
||||
<br/>
|
||||
|
||||
- 一个 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) 看板中看到开发进度，一个版本规划的新功能都开发完备后就会发版。
|
||||
|
||||
BIN
docs/image/dev/branch.png
Normal file
BIN
docs/image/dev/branch.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Reference in New Issue
Block a user