# 协作模板底本

> 本文件是 git-master 阶段 II 的**生成底本**：所有要 cp 到用户项目根的文件内容，都在这里。
> 执行时**逐字照抄**到对应路径，仅把 `{{占位符}}` 替换为阶段 I 拿到的值；平台为 Gitee/GitLab 时，issue 表单降级为 Markdown 模板（见文末）。

## 文件 1 · `.github/ISSUE_TEMPLATE/提需求.yml`

业务人员提需求 / 改动用的 issue form（仅 GitHub 支持 YAML 表单）。

```yaml
name: 提需求或改动
description: 业务人员用这个模板提需求、改动或报 Bug
title: "[需求]: "
labels: ["needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        感谢提需求！用大白话填就行，不用写代码。
        填写前可以先看看是否已有类似 issue。
  - type: dropdown
    id: type
    attributes:
      label: 这是什么类型
      options:
        - 新功能
        - 改进现有的
        - 修 Bug
    validations:
      required: true
  - type: textarea
    id: what
    attributes:
      label: 想要什么效果
      description: 用大白话描述你想要的结果
      placeholder: "比如：把首页登录按钮文案从『登录』改成『立即开始』"
    validations:
      required: true
  - type: textarea
    id: why
    attributes:
      label: 为什么要改（可选）
      description: 说一下背景，帮助开发理解优先级
      placeholder: "比如：用户反馈『登录』两字不够吸引点击"
  - type: dropdown
    id: urgency
    attributes:
      label: 紧急程度
      options:
        - 不急
        - 这周要
        - 很急
    validations:
      required: true
```

## 文件 2 · `.github/ISSUE_TEMPLATE/报bug.yml`

Bug 报告表单。**复现步骤 + 运行环境是实证里最值钱的两栏**，必须保留。

```yaml
name: 报 Bug
description: 报告一个出错的问题
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        感谢报 Bug！请尽量填全，信息越全修得越快。
  - type: textarea
    id: what-happened
    attributes:
      label: 出了什么问题
      description: 一句话描述现象
      placeholder: "比如：点登录按钮后页面白屏"
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: 怎么复现（关键）
      description: 按步骤写，让别人能照着重现
      placeholder: |
        1. 打开首页
        2. 输入账号密码
        3. 点登录
        4. 页面白屏
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: 本来应该怎样
      description: 你期望的正确结果
      placeholder: "比如：登录后跳到首页"
    validations:
      required: true
  - type: textarea
    id: environment
    attributes:
      label: 运行环境
      description: 浏览器 / 系统 / 版本（尽量写全）
      placeholder: "比如：Chrome 120 / macOS 14 / App 1.2.3"
      render: shell
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: 报错信息 / 截图（可选）
      description: 把控制台报错或截图贴上来
      render: shell
  - type: dropdown
    id: severity
    attributes:
      label: 严重程度
      options:
        - 小问题（不影响使用）
        - 中等（影响部分功能）
        - 严重（用不了）
    validations:
      required: true
```

## 文件 3 · `.github/ISSUE_TEMPLATE/config.yml`

控制 issue 模板选择器。**禁空白 issue**，强制走模板（有写权限的人仍可提空白，普通贡献者只能选模板）。

```yaml
blank_issues_enabled: false
contact_links:
  - name: 💬 提问 / 讨论
    url: "{{DISCUSSIONS_URL_OR_REMOVE}}"
    about: 不确定是不是 Bug 或需求？先来这里讨论。
  - name: 📖 使用文档
    url: "{{DOCS_URL_OR_REMOVE}}"
    about: 先看文档，你的问题可能已经有答案。
```

> 执行说明：`{{DISCUSSIONS_URL_OR_REMOVE}}` / `{{DOCS_URL_OR_REMOVE}}`——替换为真实 URL（保留引号）；若仓库没开 Discussions 或没有文档站，**整条 contact_links 删掉**，只留 `blank_issues_enabled: false`。

## 文件 4 · `.github/pull_request_template.md`

PR 模板。**核心四件套**（3747 仓库实证采用率均 ≥64%）：改动描述 / 清单 / 关联 issue / 测试证据。Markdown 格式，所有平台通用。

```markdown
## 改了什么 & 为什么
<!-- 一句话说清本次 PR 做了什么、为什么要改。reviewer 先看这句。 -->


## 关联 issue
<!-- 写 Closes #编号，合并后自动关闭 issue。每个编号单独一行。 -->
Closes #

## 类型
- [ ] 新功能
- [ ] 改进 / 优化
- [ ] 修 Bug
- [ ] 文档
- [ ] 重构（不改行为）

## 测试
- [ ] 我加了覆盖这次改动的测试
- [ ] 所有已有测试仍然通过
- [ ] 我手动测过，符合预期

## 改动影响
- [ ] 这是不向后兼容的改动（已标注迁移方式）
- [ ] 我更新了相关文档

## 截图 / 录屏（可选）
<!-- 涉及界面改动时贴上来，方便 reviewer 判断。 -->

```

> 执行说明：放在 `.github/pull_request_template.md`（仓库根 / docs / .github 三处 GitHub 都识别，默认放 .github）。

## 文件 5 · `.github/CODEOWNERS`

自动指派 review 人。格式：`<规则路径> @用户名 @团队名`。

```text
# CODEOWNERS —— 谁负责 review 哪些目录
# 格式：<文件/目录规则>  @GitHub用户名  @团队名
# 详见 https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
#
# 用阶段 I 拿到的人名替换下面的占位符；没人负责就留骨架让用户后填。

# 默认负责人（所有没被更具体规则覆盖的改动）
*                              @{{OWNER_1}}

# 按目录指派（按需放开）
# /src/backend/                @{{BACKEND_OWNER}}
# /src/frontend/               @{{FRONTEND_OWNER}}
# /docs/                       @{{DOCS_OWNER}}
# /.github/                    @{{OWNER_1}}
```

> 执行说明：`@{{OWNER_1}}` 等替换为阶段 I 确认的 GitHub 用户名；用户没给具体人 → 保留占位符并在汇报里提示"CODEOWNERS 待填"。

## 文件 6 · `CONTRIBUTING.md`

贡献指南。告诉所有人：怎么提 issue、怎么提 PR、分支怎么命名、营队链路（可选）。

```markdown
# 贡献指南

感谢参与！无论你是业务、开发还是 AI 助手，改这个项目前请先看这里。

## 一、想改东西？先开 issue

1. 去 **Issues → New issue**
2. 选模板：
   - 想要新功能 / 改东西 → **提需求或改动**
   - 出错了 → **报 Bug**
3. 填完提交。**不要提空白 issue。**

## 二、怎么改代码（开发 / AI Agent）

```
# 1. 拉代码 + 开分支（别在 main 上直接改！）
git pull
git checkout -b feat/<简短描述>      # 新功能用 feat/，改文档用 docs/，修 bug 用 fix/

# 2. 改代码（AI 在这个分支上干活）

# 3. 推上去
git push origin feat/<简短描述>

# 4. 去 GitHub 提 Pull Request，关联 issue（写 Closes #编号）
```

**分支命名约定**：
- `feat/*` 新功能
- `fix/*` 修 bug
- `docs/*` 改文档
- `refactor/*` 重构（不改行为）

## 三、PR 合并条件

1. CI 测试**全绿**（自动跑，不绿不能合）
2. 至少 1 人 review 通过（CODEOWNERS 会自动指派）
3. PR 描述写清改了什么、关联哪个 issue

## 四、铁律

- **main 受保护**，没人能直接 push，都走 PR。
- **main 上永远：文档 = 代码 = 测试**，三者一致。
- **改了行为就要同步文档**——别只改代码不改文档。
- AI Agent 只在分支上干活，绝不直接碰 main。

## 五、外部贡献者

没有仓库写权限？用 fork + PR：fork 本仓库 → 在你的 fork 改 → 从 fork 提 PR 回来。

---

> 这个项目用「200 万·AI 落地营」提示词套件开发。需求用 prd-master、设计用 design-master、测试用 tdd-master，协作规范由 git-master 配置。
```

---

## 降级：Gitee / GitLab 的 issue 模板

issue forms（YAML 表单）**只有 GitHub 支持**。Gitee / GitLab 用 Markdown 模板降级：

- 文件名改为 `.github/ISSUE_TEMPLATE/提需求.md`、`报bug.md`（`.md` 不是 `.yml`）
- 内容用 Markdown 标题 + 占位符引导填写，例如：

```markdown
## 类型
新功能 / 改进 / 修 Bug（删掉不要的）

## 想要什么效果
<!-- 用大白话描述 -->

## 为什么（可选）

## 紧急程度
不急 / 这周要 / 很急
```

- `config.yml` 在 Gitee/GitLab **不生效**，跳过生成，在 CONTRIBUTING 里说明"必须用模板提 issue"。

> 平台判定以阶段 0 的 `git remote -v` 为准；用户在阶段 I 确认。