forked from chroe/gitlink-cli
179 lines
5.3 KiB
Markdown
179 lines
5.3 KiB
Markdown
# gitlink-workflow 参考手册
|
||
|
||
> 本文档定义跨模块工作流的 API 字段映射、Fork 协作流程和分支命名规范。
|
||
|
||
---
|
||
|
||
## 一、跨模块 API 字段关联
|
||
|
||
### 核心关联关系
|
||
|
||
```
|
||
repo +info
|
||
├── project_id ──────────────────→ milestone +list (project_id)
|
||
├── forked_from_project_id ──────→ upstream 仓库标识
|
||
├── open_devops ─────────────────→ ci +builds 可用性
|
||
└── default_branch ──────────────→ branch +protect 的目标
|
||
|
||
pr +create
|
||
├── --head <user>:<branch> ──────→ branch +create 的产物
|
||
├── --base <branch> ─────────────→ 目标分支（通常 master）
|
||
└── pr +view 返回的 id ──────────→ pr +merge / pr +files 的参数
|
||
|
||
issue +create
|
||
└── 返回的 project_issues_index ──→ issue +close / issue +comment 的 --number
|
||
```
|
||
|
||
### PR 状态映射
|
||
|
||
| pull_request_status | 含义 | 对应 `--state` |
|
||
|---------------------|------|---------------|
|
||
| 0 | 开放 | open |
|
||
| 1 | 已合并 | merged |
|
||
| 2 | 已关闭 | closed |
|
||
|
||
> ⚠️ `pr +list --state` 参数仅影响统计计数，返回列表可能包含所有状态。客户端需按 `pull_request_status` 字段过滤。
|
||
|
||
### PR 合并方式
|
||
|
||
| `--do` 参数 | 说明 |
|
||
|------------|------|
|
||
| `merge` | 标准合并（创建 merge commit） |
|
||
| `rebase` | Rebase 合并（线性历史） |
|
||
| `squash` | Squash 合并（压缩为单个 commit） |
|
||
|
||
---
|
||
|
||
## 二、Fork 协作流程（详细版）
|
||
|
||
### 何时必须 Fork
|
||
|
||
- 向**非自己拥有**的仓库提交 PR
|
||
- 没有目标仓库的写权限
|
||
- 即使是仓库成员，也推荐 Fork 流程
|
||
|
||
### 完整 Fork 工作流
|
||
|
||
```bash
|
||
# 1. Fork 目标仓库
|
||
gitlink-cli repo +fork --owner <target-org> --repo <target-repo>
|
||
|
||
# 2. 克隆自己的 Fork
|
||
git clone https://gitlink.org.cn/<my-username>/<target-repo>.git
|
||
cd <target-repo>
|
||
|
||
# 3. 添加上游 remote
|
||
git remote add upstream https://gitlink.org.cn/<target-org>/<target-repo>.git
|
||
|
||
# 4. 同步上游最新代码
|
||
git fetch upstream
|
||
git checkout master
|
||
git merge upstream/master
|
||
git push origin master
|
||
|
||
# 5. 创建功能分支
|
||
git checkout -b feature/my-change
|
||
|
||
# 6. 开发和提交
|
||
git add -A
|
||
git commit -m "feat: 我的改动"
|
||
|
||
# 7. 推送到自己的 Fork
|
||
git push origin feature/my-change
|
||
|
||
# 8. 从 Fork 向主仓库提 PR
|
||
gitlink-cli pr +create \
|
||
--owner <target-org> --repo <target-repo> \
|
||
--head <my-username>:feature/my-change \
|
||
--base master \
|
||
--title "feat: 我的改动"
|
||
|
||
# 9. 上游有更新时同步
|
||
git fetch upstream
|
||
git merge upstream/master
|
||
git push origin master
|
||
```
|
||
|
||
### 禁止操作
|
||
|
||
- ❌ 直接 clone 主仓库后 push（污染主仓库）
|
||
- ❌ 向主仓库的 master 分支直接推送
|
||
- ❌ 使用 `--force` push 到任何共享分支
|
||
|
||
---
|
||
|
||
## 三、分支命名规范
|
||
|
||
### 推荐命名
|
||
|
||
| 类型 | 模式 | 示例 |
|
||
|------|------|------|
|
||
| 新功能 | `feature/<描述>` | `feature/wiki-create` |
|
||
| Bug 修复 | `fix/<描述>` | `fix/batch-url-encoding` |
|
||
| 文档 | `docs/<描述>` | `docs/api-reference` |
|
||
| 重构 | `refactor/<描述>` | `refactor/auth-module` |
|
||
| 发布准备 | `release/<版本>` | `release/v1.0.0` |
|
||
| 紧急修复 | `hotfix/<描述>` | `hotfix/critical-bug` |
|
||
|
||
### GitLink 分支映射
|
||
|
||
| 平台 | 默认主分支 |
|
||
|------|-----------|
|
||
| GitLink | `master` |
|
||
| GitHub | `main` |
|
||
|
||
gitlink-cli 在与 GitLink 交互时自动处理映射：
|
||
- push 时：`main` → `master`
|
||
- pull 时：`master` → `main`
|
||
|
||
---
|
||
|
||
## 四、项目初始化清单
|
||
|
||
完整的项目初始化应覆盖以下全部：
|
||
|
||
| 序号 | 项目 | 命令 |
|
||
|------|------|------|
|
||
| 1 | 创建仓库 | `repo +create` |
|
||
| 2 | 克隆到本地 | `repo +clone` |
|
||
| 3 | 创建 README | 本地创建后 git push |
|
||
| 4 | 创建 .gitignore | 本地创建后 git push |
|
||
| 5 | 保护主分支 | `branch +protect --name master` |
|
||
| 6 | 创建开发分支 | `branch +create --name develop` |
|
||
| 7 | 创建初始 Issue | `issue +create` |
|
||
| 8 | 创建里程碑 | `milestone +create` |
|
||
| 9 | 开启 DevOps | `api POST /.../activate` |
|
||
| 10 | 配置流水线 | 创建 `.devops/` 目录和 YAML 文件 |
|
||
| 11 | 邀请团队成员 | `org +batch-invite`（组织仓库）或 `member +add` |
|
||
|
||
---
|
||
|
||
## 五、已知限制
|
||
|
||
| 限制 | 说明 |
|
||
|------|------|
|
||
| PR 创建需要代码差异 | 分支内容必须与目标分支不同，否则 GitLink 拒绝创建 |
|
||
| `api POST` 有 URL bug | 部分 Raw API 写操作不可用，优先使用 shortcuts |
|
||
| 不能删除远程分支 | `branch +delete` 的 API 不可用（GitLink 平台 bug） |
|
||
| PR state 过滤不精确 | `pr +list --state` 仅影响计数，需客户端二次过滤 |
|
||
|
||
---
|
||
|
||
## 六、常见问题
|
||
|
||
### Q: 创建 PR 时报错"无变更"？
|
||
|
||
A: 确认你的分支上有不同于 base 分支的新 commit。如果是刚创建的空白分支，先提交代码再创建 PR。
|
||
|
||
### Q: PR 合并后需要手动删分支吗？
|
||
|
||
A: GitLink 目前不自动删除合并后的分支。可以用 `git push origin --delete <branch>` 或通过 Web 页面手动删除。
|
||
|
||
### Q: 如何同步 Fork 仓库与上游？
|
||
|
||
A: `git fetch upstream && git merge upstream/master && git push origin master`
|
||
|
||
### Q: 项目初始化后 DevOps 还是不可用？
|
||
|
||
A: `api POST /activate` 可能因 URL bug 失败。最可靠的方式是在 GitLink Web 页面手动开启。
|