# 贡献指南

TVU Design System 团队协作流程，越简单越好。

## 4 步流程

> 💡 **关于分支**：Gitea 仓库里**只有一个常驻分支 `master`**。要做改动时，你**自己在本地新建一个 feature 分支**（命令 `git checkout -b`），改完 push 上去，Gitea 才会显示这个新分支。合并到 master 后这个分支就删掉了。所以分支列表平时是空的，看到只有 master 是正常的。

```bash
# 1. 切到 master 拉最新代码
git checkout master
git pull

# 2. 新建一个 feature 分支（分支名见下面"分支命名"）
git checkout -b feat/your-change

# 3. 改完 commit + push
git add .
git commit -m "feat(button): add loading state"
git push -u origin feat/your-change

# 4. 在 Gitea 网页上发 PR → 找同事 review → approve → 合并 → 删分支
```

## 分支命名

| 前缀 | 用途 |
|------|------|
| `feat/` | 新功能 / 新组件 |
| `fix/` | Bug 修复 |
| `docs/` | 文档 |
| `chore/` | 依赖、配置、构建 |

## Commit 规范

`类型(范围): 简短描述`，比如 `fix(input): correct focus ring color`。

## 两条铁律

- ❌ 团队成员不要直接 push 到 `master`（owner 阶段性除外，见下"Owner 阶段"段）
- ❌ 不要硬编码颜色 / 间距 / 字号，必须用设计 token
- ❌ 从消费 / 外部项目回流规则时只带**规则文本**，不要把那个项目的复盘 / 过程实录带进本仓库（`docs/internal/retrospection/` 仅限设计系统自身工作的复盘）。详见 [`docs/meta-rules.md` 触发器 B §回流边界](./docs/meta-rules.md)

## Owner 阶段

当前 owner（@NancyZeng0210）是事实上的 solo maintainer——所有改动**可直接 push 到 master**，不强制走 PR。

理由：单点维护时 PR 自审无 reviewer 价值，commit message + git log 已是足够的 audit trail。

触发"团队 PR 模式"的条件：**Owner 主动要求**（例：发版前最后一改希望多眼审 / 架构重决策想留 PR 评论 trail）。

## 本地命令

```bash
pnpm install        # 装依赖
pnpm playground     # 本地预览
pnpm test           # 跑测试
pnpm lint           # 代码规范
```

## 团队仓库约定

`ux-team` 组织下的仓库分两类：

**共享维护**（如 TVU Design System）
- 所有成员可改，按上面的 4 步流程走 PR

**个人项目**（成员自己建的）
- 技术上所有成员都有 Write 权限，但默认"谁建归谁管"
- 想协作请先开 Issue 或 PR，未经创建者同意请勿直接 push

> ⚠️ 新建仓库时，记得把 **Owner** 下拉切换到 `ux-team`，否则会建到个人账号下。工作相关的仓库都应建在组织下，方便沉淀和交接。

## 发版（仅维护者）

1. 更新 [CHANGELOG.md](./CHANGELOG.md) 和 `package.json` 版本号
2. `git tag v0.x.x && git push --tags`
3. 发布到 npm