gitlink-cli/docs/UPSTREAM_PR_GUIDE.md

上游 PR 提交手册（子赛题一·成果落地）

目标：把本 fork 的成熟成果以 PR 形式提交到真正上游 gitlink/gitlink-cli，争取"已提交且通过 CI"基础分 → "被合并"高分。 本手册由 Claude 生成，push 与开 PR 需用你的 GitLink 账号执行（我不能代操作）。

0. 一次性准备：配置 upstream 远程

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 为例）

# 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 描述模板（直接复制填）

## 背景
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 收录（子赛题二）

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"计基础分。