112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# STORAGE LABOS 团队协作指南
|
||
|
||
本文是团队日常 Git 操作的简明入口；完整工程约束见
|
||
[ProjectManual.md](ProjectManual.md) 第 13 章。
|
||
|
||
## 1. 首次加入项目
|
||
|
||
公开仓库允许匿名克隆；需要提交代码、Issue 或 Pull Request 的成员先注册账号并由管理员批准：
|
||
|
||
```bash
|
||
git clone https://git.imagebrewing.com/yuanshuai/storage-labos.git
|
||
cd storage-labos/flashops
|
||
make setup
|
||
make test
|
||
```
|
||
|
||
不要通过聊天工具传递压缩包继续开发；Git 仓库是代码和文档的唯一版本来源。
|
||
|
||
## 2. 分支规则
|
||
|
||
- `main`：始终保持测试通过和可发布，禁止直接开发或强制推送。
|
||
- `feat/<short-name>`：功能开发。
|
||
- `fix/<short-name>`：缺陷修复。
|
||
- `docs/<short-name>`：纯文档变更。
|
||
- `chore/<short-name>`：构建、依赖、部署与仓库维护。
|
||
|
||
一项工作一个分支；不要把无关功能、生产配置和大规模格式化混在同一分支。
|
||
|
||
```bash
|
||
git switch main
|
||
git pull --ff-only
|
||
git switch -c feat/agent-step-lease
|
||
```
|
||
|
||
## 3. 提交前质量门
|
||
|
||
```bash
|
||
cd flashops
|
||
make test
|
||
make demo
|
||
```
|
||
|
||
回到仓库根目录后，只暂存本次工作涉及的文件：
|
||
|
||
```bash
|
||
git status -sb
|
||
git add <明确的文件或目录>
|
||
git diff --cached --stat
|
||
git diff --cached --check
|
||
```
|
||
|
||
混合工作区不要直接使用 `git add -A`，避免把别人的改动、数据库或临时文件带入提交。
|
||
|
||
## 4. 提交格式
|
||
|
||
使用 Conventional Commits：`type(scope): subject`。
|
||
|
||
| 类型 | 用途 | 示例 |
|
||
|---|---|---|
|
||
| `feat` | 新功能 | `feat(agent): add step lease polling` |
|
||
| `fix` | 缺陷修复 | `fix(safety): reject stale host heartbeat` |
|
||
| `docs` | 文档 | `docs(manual): add agent deployment guide` |
|
||
| `test` | 测试 | `test(agent): cover token rotation` |
|
||
| `refactor` | 不改变行为的重构 | `refactor(events): isolate projection writer` |
|
||
| `perf` | 性能优化 | `perf(api): reduce timeline query cost` |
|
||
| `chore` | 工具、依赖和部署 | `chore(ci): add Python test matrix` |
|
||
|
||
主题用祈使语气、简短明确；一次提交只表达一个完整意图。
|
||
|
||
## 5. 推送与 Pull Request
|
||
|
||
```bash
|
||
git commit -m "feat(agent): add step lease polling"
|
||
git push -u origin "$(git branch --show-current)"
|
||
```
|
||
|
||
在 Gitea 创建 Pull Request，并写清：改了什么、为什么改、影响范围、验证结果和风险。
|
||
至少一名团队成员评审且质量门通过后才能合并。当前 Gitea 未在生产服务器上启用自托管
|
||
Runner，提交者必须在 PR 中附上本地测试结果；未来接入隔离 CI Runner 后再把自动检查设为
|
||
必需。优先使用 Squash merge，PR 标题保持 Conventional Commit 格式；合并后删除远程功能分支。
|
||
|
||
评审者重点检查：
|
||
|
||
1. 安全门禁、状态机和事件写路径是否被绕过；
|
||
2. 是否新增或修改测试；
|
||
3. API、数据结构、配置或部署变化是否同步更新手册；
|
||
4. 是否包含凭据、生产数据、日志、构建产物或大文件；
|
||
5. 危险动作是否仍为默认拒绝。
|
||
|
||
## 6. 冲突与回退
|
||
|
||
功能分支同步 `main` 时使用团队统一方式；首阶段建议 rebase：
|
||
|
||
```bash
|
||
git fetch origin
|
||
git rebase origin/main
|
||
```
|
||
|
||
仅允许对自己尚未合并的功能分支执行 `git push --force-with-lease`；严禁对 `main` 强推。
|
||
已合并变更需要撤销时使用 `git revert <commit>`，不要改写共享历史。
|
||
|
||
## 7. 绝不能提交的内容
|
||
|
||
- `.env`、密码、Token、SSH 私钥、证书私钥；
|
||
- `flashops/var/`、SQLite 数据库、Evidence Bundle 和日志；
|
||
- `.venv/`、`node_modules/`、缓存和本机构建产物；
|
||
- `~/.flashops/agent-state.json` 或任何 Agent 原始 bearer token；
|
||
- 未脱敏的客户数据、设备序列号清单和生产备份。
|
||
|
||
如果凭据误入提交：立即停止推送、通知管理员轮换凭据，再清理历史；仅删除当前文件不等于
|
||
从 Git 历史中删除。
|