b29c12d5e5
Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# 团队协作
|
||
|
||
SF 支持多人并行工作流，让多个开发者可以同时在同一个仓库中工作。
|
||
|
||
## 设置
|
||
|
||
### 1. 启用 Team Mode
|
||
|
||
为团队使用配置 SF 的最简单方法，是在项目偏好中设置 `mode: team`。这会一次性开启唯一 milestone ID、推送分支和预合并检查：
|
||
|
||
```yaml
|
||
# .sf/PREFERENCES.md（项目级，提交到 git）
|
||
---
|
||
version: 1
|
||
mode: team
|
||
---
|
||
```
|
||
|
||
这相当于手动设置 `unique_milestone_ids: true`、`git.push_branches: true`、`git.pre_merge_check: true` 以及其他适合团队协作的默认值。你仍然可以覆盖单个选项，例如如果团队偏好自动推送，也可以在 `mode: team` 基础上再加 `git.auto_push: true`。
|
||
|
||
你也可以不使用 mode，而是单独配置每一项设置（详见 [Git 策略](git-strategy.md)）。
|
||
|
||
### 2. 配置 `.gitignore`
|
||
|
||
共享规划产物（milestones、roadmaps、decisions），同时把运行时文件保留在本地：
|
||
|
||
```bash
|
||
# ── SF：运行时 / 临时文件（按开发者、按会话隔离）──────
|
||
.sf/auto.lock
|
||
.sf/completed-units.json
|
||
.sf/STATE.md
|
||
.sf/metrics.json
|
||
.sf/activity/
|
||
.sf/runtime/
|
||
.sf/worktrees/
|
||
.sf/milestones/**/continue.md
|
||
.sf/milestones/**/*-CONTINUE.md
|
||
```
|
||
|
||
**会共享的内容**（提交到 git）：
|
||
|
||
- `.sf/PREFERENCES.md`：项目偏好
|
||
- `.sf/PROJECT.md`：持续维护的项目描述
|
||
- `.sf/REQUIREMENTS.md`：需求契约
|
||
- `.sf/DECISIONS.md`：架构决策
|
||
- `.sf/milestones/`：roadmaps、plans、summaries 和 research
|
||
|
||
**仅保留本地的内容**（gitignore）：
|
||
|
||
- 锁文件、指标、状态缓存、运行时记录、worktrees、活动日志
|
||
|
||
### 3. 提交偏好设置
|
||
|
||
```bash
|
||
git add .sf/PREFERENCES.md
|
||
git commit -m "chore: enable SF team workflow"
|
||
```
|
||
|
||
## `commit_docs: false`
|
||
|
||
如果团队里只有部分成员使用 SF，或者公司策略要求仓库保持干净：
|
||
|
||
```yaml
|
||
git:
|
||
commit_docs: false
|
||
```
|
||
|
||
这会把整个 `.sf/` 加入 `.gitignore`，让所有产物都保留在本地。这样使用 SF 的开发者仍然能获得结构化规划的好处，而不会影响不使用 SF 的同事。
|
||
|
||
## 迁移现有项目
|
||
|
||
如果你当前项目里对 `.sf/` 做了整目录忽略：
|
||
|
||
1. 确保当前没有进行中的 milestones（工作区状态干净）
|
||
2. 按上面的选择性规则更新 `.gitignore`
|
||
3. 在 `.sf/PREFERENCES.md` 中添加 `unique_milestone_ids: true`
|
||
4. 如有需要，重命名现有 milestones 以使用唯一 ID：
|
||
```
|
||
I have turned on unique milestone ids, please update all old milestone
|
||
ids to use this new format e.g. M001-abc123 where abc123 is a random
|
||
6 char lowercase alpha numeric string. Update all references in all
|
||
.sf file contents, file names and directory names. Validate your work
|
||
once done to ensure referential integrity.
|
||
```
|
||
5. 提交修改
|
||
|
||
## 并行开发
|
||
|
||
多个开发者可以同时对不同 milestones 运行自动模式。每个开发者都会：
|
||
|
||
- 获得自己的 worktree（`.sf/worktrees/<MID>/`，已加入 gitignore）
|
||
- 在独立的 `milestone/<MID>` 分支上工作
|
||
- 独立地 squash merge 回主分支
|
||
|
||
milestone 依赖可以通过 `M00X-CONTEXT.md` frontmatter 声明：
|
||
|
||
```yaml
|
||
---
|
||
depends_on: [M001-eh88as]
|
||
---
|
||
```
|
||
|
||
SF 会强制要求上游依赖 milestone 先完成，之后才会启动下游工作。
|