forked from Gitlink/gitlink-cli
112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
# 上游 PR 提交手册（子赛题一·成果落地）
|
||
|
||
> 目标：把本 fork 的成熟成果以 PR 形式提交到真正上游 `gitlink/gitlink-cli`，争取"已提交且通过 CI"基础分 → "被合并"高分。
|
||
> 本手册由 Claude 生成，**push 与开 PR 需用你的 GitLink 账号执行**（我不能代操作）。
|
||
|
||
## 0. 一次性准备：配置 upstream 远程
|
||
|
||
```bash
|
||
cd gitlink-cli
|
||
git remote add upstream https://gitlink.org.cn/gitlink/gitlink-cli.git
|
||
git fetch upstream
|
||
git fetch origin
|
||
# 确认
|
||
git remote -v # 应看到 origin(jiangtx) + upstream(gitlink)
|
||
```
|
||
|
||
## 1. 选哪些成果提（质量优先，建议 3–4 个 PR）
|
||
|
||
按"自带测试 + 自带文档 + 改动聚焦"挑选，下面的 commit 哈希均为本 fork 已验证的干净 feature 提交：
|
||
|
||
| PR | 主题 | 源 commit | 含测试 | 含文档 |
|
||
|---|---|---|---|---|
|
||
| **PR-1** | wiki 命令（5 条） | `6bcd8b6` | ✅ | ✅ |
|
||
| **PR-2** | pm 命令（6 条） | `b4cfdb7` | ✅ | ✅ |
|
||
| **PR-3** | export 命令（3 条） | `2cc0e5c` | ✅ | ✅ |
|
||
| **PR-4** | alias/browse/status（开发者体验） | `a28a8ea` + `9474c1f`(测试) | ✅ | ✅ |
|
||
| **PR-5** | pipeline 命令 | 见 `git log -- shortcuts/pipeline/` | ✅ | ✅ |
|
||
| **PR-6** | webhook 命令 | 见 `git log -- shortcuts/webhook/` | ✅ | ✅ |
|
||
| **PR-7（Skill 收录）** | gitlink-research-tracker Skill | 见 `git log -- skills/gitlink-research-tracker/` | — | ✅ |
|
||
|
||
> 建议**先提 PR-1 / PR-2 / PR-7**这三个最干净、最有代表性的。其余视维护者反馈再提。
|
||
|
||
## 2. 单个 PR 的标准流程（以 PR-1 wiki 为例）
|
||
|
||
```bash
|
||
# 1) 基于上游 master 建干净分支
|
||
git checkout -b pr-shortcut-wiki upstream/master
|
||
|
||
# 2) 挑入对应 commit（如只一个就用 cherry-pick；多个依次挑）
|
||
git cherry-pick 6bcd8b6
|
||
# 若 wiki 的帮助/变更文档在别的 commit，也一并 cherry-pick
|
||
|
||
# 3) 本地校验（需 Go；无 Go 则跳过，靠上游 CI）
|
||
go build ./... && go vet ./... && go test ./shortcuts/wiki/... && gofmt -l .
|
||
|
||
# 4) 推到 fork
|
||
git push origin pr-shortcut-wiki
|
||
|
||
# 5) 到 GitLink 网页：jiangtx/gitlink-cli → 合并请求 → 新建 → 源分支 pr-shortcut-wiki → 目标 gitlink/gitlink-cli:master
|
||
```
|
||
|
||
> 若 cherry-pick 与上游冲突，通常是因为上游同期也改了 `register.go`。解决：手动把你的模块加进 `groups` map 与 `descriptions` map 即可。
|
||
|
||
## 3. PR 描述模板（直接复制填）
|
||
|
||
```markdown
|
||
## 背景
|
||
gitlink-cli 缺少 XXX 命令，需手工拼 Raw API。本 PR 新增 `xxx` 命令组。
|
||
|
||
## 改动
|
||
- 新增 `shortcuts/xxx/`：N 条子命令（list/create/...）
|
||
- 新增单元测试 `shortcuts/xxx/*_test.go`（覆盖 method/path/query/payload）
|
||
- 新增帮助文档 `doc/commands/xxx.md` + 变更说明 `doc/changes/xxx-shortcut.md`
|
||
|
||
## 对应 OpenAPI
|
||
- GET/POST `/v1/:owner/:repo/...`
|
||
|
||
## 测试方式
|
||
\`\`\`bash
|
||
go test ./shortcuts/xxx/... -race
|
||
gofmt -l shortcuts/xxx/
|
||
\`\`\`
|
||
|
||
## 截图
|
||
（贴 1–2 张命令运行截图）
|
||
|
||
## 关联
|
||
竞赛：GitLink 大赛 2026 子赛题一。fork：jiangtx/gitlink-cli。
|
||
```
|
||
|
||
## 4. PR-7·Skill 收录（子赛题二）
|
||
|
||
```bash
|
||
git checkout -b pr-skill-research-tracker upstream/master
|
||
git cherry-pick <research-tracker 的 commit>
|
||
git push origin pr-skill-research-tracker
|
||
# 目标：gitlink/gitlink-cli:master，路径 skills/gitlink-research-tracker/
|
||
```
|
||
|
||
PR 描述要点：
|
||
- 说明这是**科研辅助场景**（技术调研：多关键词搜索→成熟度评分→趋势→选型），与现有 Skill 不重复
|
||
- 附 `EXAMPLES.md` 里的 Agent 验证结果（调用次数/token/耗时/输出）
|
||
- 注明兼容 Claude Code（已验证）/ OpenClaw / Cursor
|
||
|
||
## 5. 提交后：更新 README 的 PR 清单
|
||
|
||
每个 PR 开好后，回到本仓库 `README.md` 的「上游 PR 清单」表格，把 `_待提交_` 换成真实 PR 靶向链接与状态，并 commit。这是评委看到"成果落地"的直接证据。
|
||
|
||
## 6. 提交前自查清单（每个 PR 必须全绿）
|
||
|
||
- [ ] `go build ./...` 通过
|
||
- [ ] `go test ./... -race` 通过
|
||
- [ ] `gofmt -l .` 无输出（无未格式化文件）
|
||
- [ ] 含单元测试
|
||
- [ ] 含 `doc/commands/*.md` + `doc/changes/*.md`
|
||
- [ ] PR 描述用模板
|
||
- [ ] 不夹带无关改动（一个 PR 只做一件事）
|
||
|
||
## 7. 时间策略
|
||
|
||
今天（7/8）就提 PR-1、PR-2、PR-7。维护者 Review 1–2 周，越早提越可能合并。截止日仍在 Review 的，竞赛按"已提交且通过 CI"计基础分。
|