mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:15:14 +08:00
72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
# 贡献指南
|
||
|
||
感谢参与 BlueArchive Toolkit。这个项目按长期维护的开源工具链标准推进，不接受只为临时通过、不可维护或污染本地资源目录的改动。
|
||
|
||
## 开始前
|
||
|
||
1. 阅读 `README.md`、`CURRENT_STATUS.md` 和 `docs/reports/CURRENT_GAPS.md`，确认当前实现状态和优先级。
|
||
2. 涉及官方资源同步、Rust 后端、Go CLI 或架构边界时，额外阅读 `docs/guides/development.md`、`docs/guides/official-resource-test-pull.md` 和相关 ADR。
|
||
3. AI agent 或自动化助手还必须遵守 `AGENTS.md`。
|
||
|
||
## 工作流
|
||
|
||
1. 基于当前开发分支创建功能分支。
|
||
2. 先分析现有文档和代码，再决定实现方式。
|
||
3. 保持改动聚焦，避免无关重构、批量格式化或元数据 churn。
|
||
4. 实现后运行覆盖改动范围的测试、格式化和 lint。
|
||
5. 如果用户可见行为、运行命令、架构边界、缺口状态或数据格式发生变化，同步更新文档。
|
||
|
||
## 提交规范
|
||
|
||
提交信息使用 Conventional Commits：
|
||
|
||
- 必须使用 `type(scope): 中文说明` 格式。
|
||
- `type` 使用 `feat`、`fix`、`docs`、`test`、`refactor`、`chore` 等 Conventional Commits 类型。
|
||
- `scope` 必须写具体模块或文档域，例如 `ffi`、`docs`、`cli`、`cas`、`official-sync`。
|
||
|
||
提交说明默认使用简体中文。代码标识符和协议字段仍使用英文。
|
||
|
||
示例：
|
||
|
||
- `feat(cli): 添加 doctor 命令骨架`
|
||
- `fix(docs): 修正官方同步运行说明`
|
||
- `refactor(ffi): 降级 FFI 为可选兼容层`
|
||
|
||
## 验证要求
|
||
|
||
基础验证命令见 `docs/guides/development.md`。常用最低门禁：
|
||
|
||
```bash
|
||
cargo fmt --check
|
||
cargo test --workspace
|
||
cargo clippy --workspace -- -D warnings
|
||
```
|
||
|
||
如果改动只影响部分 crate，可以先跑更窄的测试，但合并前必须确保影响面被覆盖。官方资源同步、下载、daemon、status、verify 或 repair 相关改动还应运行：
|
||
|
||
```bash
|
||
cargo test -p bat-infrastructure --bin bat -- --nocapture
|
||
cargo test -p bat-infrastructure -- --nocapture
|
||
```
|
||
|
||
真实官方网络 smoke run 必须写入隔离目录，禁止写入现有游戏客户端或生产资源目录。
|
||
|
||
## 资源和数据安全
|
||
|
||
1. 不要把生产环境当作开发环境。
|
||
2. 不要默认读取或修改 `/home/wanye/D/BlueArchive` 等已有资源目录。
|
||
3. 不要提交真实账号、token、cookie、私有路径、下载产物、数据库或本地 CAS 数据。
|
||
4. 新增 fixture 应尽量最小化，只保留验证解析、校验或错误处理所需的数据。
|
||
|
||
## PR 要求
|
||
|
||
PR 描述应包含：
|
||
|
||
1. 改动摘要。
|
||
2. 影响范围。
|
||
3. 已运行的验证命令。
|
||
4. 未覆盖风险或后续缺口。
|
||
5. 相关 issue、ADR 或文档链接。
|
||
|
||
如果改动关闭缺口或 issue，请在 PR 或提交中明确引用。
|