PR前必须配置upstream远程仓库，否则90%的PR会因冲突被拒；需执行git remote add upstream原仓库地址，并通过git fetch upstream、git merge upstream/main同步最新代码。
PR前必须配置 upstream 远程仓库
不配 upstream 就直接改代码，90% 的 PR 会因冲突被拒或反复 rebase。你的 Fork 是静态快照，原项目每天都在更新，git remote add upstream https://github.com/original-owner/repo.git 才能拉取最新主线代码。
常见错误现象：本地 main 分支落后上游几十个 commit，push 后 GitHub 显示 “This pull request has conflicts that must be resolved”，点开一看全是无关的旧提交。
- 执行
git remote -v确认输出里有upstream对应原仓库地址（fetch/push 均需存在） - 别用
git pull origin main同步——那是同步你自己的 Fork，不是上游 - 日常开发前固定三步：
git fetch upstream→git checkout main→git merge upstream/main
分支命名必须带类型前缀和语义描述
GitHub 上看到 patch-1、test、fix 这类分支名，维护者大概率直接忽略。分支名是第一道筛选器，它得让 reviewer 一眼判断改动性质和范围。
真实协作中，feat/add-api-rate-limit 比 feature123 多出三倍通过率，因为前者自带上下文，后者需要点开 diff 才知道改了啥。
- 强制使用
feat/、fix/、docs/、refactor/等前缀，禁止裸名分支 - 描述部分用短横线连接小写单词，避免空格或下划线（
fix/user-login-null-pointer✅，fix/user login null pointer❌） - 如果关联 Issue，建议嵌入编号：
fix/27-api-timeout-handling
PR 描述里必须包含可验证的行为变更
只写“修复了一个 bug”或“优化了性能”等于没写。维护者没法验证，CI 也没法覆盖，结果就是卡在 review 环节，或者合并后才发现逻辑错位。
典型失败案例：PR 标题是 Update README.md，描述空白，实际改了核心函数签名但没提——下游用户升级后直接 panic。
- 开头用一句话说明“改了什么 + 为什么改”，例如：
Fix panic when config file is missing by adding early validation - 列出具体变更点：
- Add nil check before accessing Config.APIKey、- Return descriptive error instead of generic 'invalid config' - 附上本地验证方式：
Run <code>go test -run TestLoadConfig_MissingFile→ passes - 若影响接口或行为，明确标注 BREAKING CHANGE 或兼容性说明
推送前务必运行本地 CI 脚本和格式检查
很多 PR 被拒不是逻辑问题，而是卡在 lint、test、build 这些自动化门禁上。GitHub Actions 报 npm run lint failed，你再重推一次，又等 5 分钟——其实本地 npm run lint 早就该告诉你哪行少了分号。
不同项目 CI 差异大：make test、poetry run pytest、bundle exec rspec 都可能成为门槛，不跑就等于裸奔。
- 先看项目根目录的
.github/workflows/或Makefile，找到主测试命令 - 执行前确保环境一致：Python 版本、Node.js 版本、Go module proxy 设置需匹配 CI 配置
- 格式工具如
prettier、gofmt、ruff建议加到 Git hook，避免每次手动记 - CI 失败日志里出现
undefined reference to 'xxx'，大概率是本地没跑make build就直接 push
实际协作中最容易被忽略的，不是某条命令怎么敲，而是把 PR 当成「提交代码」而不是「交付可验证变更」——描述里没行为说明、分支名没类型、本地没跑测试，这些细节堆在一起，会让维护者本能地推迟 review。
