GitHub提交到公共项目流程

GitHub 提交到公共项目流程

目录

1. 项目类型对比
2. 自己项目的操作流程
3. 公共项目贡献流程
4. Changeset 使用详解
5. 常见问题和解决方案

项目类型对比

自己的项目 vs 公共开源项目

自己项目的操作流程

基础流程（3步完成）

# 1. 添加更改到暂存区
git add .
# 或添加特定文件
git add filename.js

# 2. 提交更改
git commit -m "描述你的更改"

# 3. 推送到远程仓库
git push origin main
# 或推送到其他分支
git push origin develop

常用操作

创建新分支开发

# 创建并切换到新分支
git checkout -b feature/new-feature

# 开发完成后推送
git push origin feature/new-feature

# 如果需要，可以直接合并到主分支
git checkout main
git merge feature/new-feature
git push origin main

查看状态和历史

# 查看当前状态
git status

# 查看提交历史
git log --oneline

# 查看分支列表
git branch

# 查看远程分支
git branch -r

撤销和修改

# 撤销暂存区的文件
git reset filename.js

# 修改最后一次提交信息
git commit --amend -m "新的提交信息"

# 回退到上一个提交
git reset --hard HEAD~1

公共项目贡献流程

完整操作步骤

1. Fork 项目

# 在 GitHub 网页上点击项目的 "Fork" 按钮
# 然后克隆你的 fork
git clone https://github.com/你的用户名/项目名.git
cd 项目名

2. 配置远程仓库

# 添加原项目为上游仓库
git remote add upstream https://github.com/原作者/项目名.git

# 查看远程仓库配置
git remote -v
# 输出：
# origin    https://github.com/你的用户名/项目名.git (fetch)
# origin    https://github.com/你的用户名/项目名.git (push)
# upstream  https://github.com/原作者/项目名.git (fetch)
# upstream  https://github.com/原作者/项目名.git (push)

3. 同步最新代码

# 获取上游仓库最新代码
git fetch upstream

# 切换到主分支并合并
git checkout main
git merge upstream/main

# 推送到你的 fork
git push origin main

4. 创建功能分支

# 创建并切换到新分支
git checkout -b feature/your-feature-name

# 分支命名规范：
# feature/功能名     - 新功能
# bugfix/问题描述    - 修复bug
# docs/文档更新      - 文档更新
# hotfix/紧急修复    - 紧急修复

5. 开发和测试

# 修改代码...

# 运行测试确保没有破坏现有功能
npm test
# 或
yarn test

# 检查代码风格
npm run lint
# 或
yarn lint

# 如果有格式化工具
npm run format

6. 提交更改

# 查看更改
git status
git diff

# 添加文件到暂存区
git add .
# 或添加特定文件
git add src/modified-file.js

# 提交更改（使用清晰的提交信息）
git commit -m "Add proxy support for contract verification

- Detect local proxy settings
- Create HTTP dispatcher with proxy agent
- Fix ECONNREFUSED errors in restricted networks
- Maintain backward compatibility"

7. 推送分支

# 推送到你的 fork
git push origin feature/your-feature-name

# 如果是第一次推送这个分支
git push -u origin feature/your-feature-name

8. 创建 Pull Request

在 GitHub 网页上：

1. 访问你的 fork 仓库
2. 点击 “Compare & pull request” 按钮
3. 填写 PR 标题和描述：

## 描述
添加代理支持以修复受限网络环境中的合约验证问题

## 更改内容
- 添加本地代理检测功能
- 创建支持代理的 HTTP 调度器
- 修复 ECONNREFUSED 错误
- 保持向后兼容性

## 测试
- [x] 单元测试通过
- [x] 在有代理的环境中测试
- [x] 在无代理的环境中测试

## 相关问题
Fixes #1234

9. 响应审核反馈

# 如果需要修改代码
# 在同一分支继续开发
git add .
git commit -m "Address review feedback: improve error handling"
git push origin feature/your-feature-name

# PR 会自动更新

Changeset 使用详解

什么是 Changeset？

Changeset 是一个版本管理工具，用于：

• 跟踪包的版本变更
• 自动生成 changelog
• 管理 monorepo 中多个包的版本
• 确保语义化版本控制

检查项目是否使用 Changeset

# 查看是否有 .changeset 目录
ls -la | grep changeset

# 查看 package.json 中的依赖
cat package.json | grep changeset

# 查看是否有 changeset 配置
cat .changeset/config.json

初始化 Changeset（如果需要）

# 初始化 changeset
npx changeset init

# 这会创建 .changeset 目录和配置文件

创建 Changeset

方法一：交互式创建（推荐）

# 运行 changeset 命令
npx changeset

# 按照提示操作：
# 1. 选择要更新的包（用空格键选择，回车确认）
# 2. 选择版本类型：
#    - major: 破坏性更改 (1.0.0 → 2.0.0)
#    - minor: 新功能，向后兼容 (1.0.0 → 1.1.0)  
#    - patch: bug修复 (1.0.0 → 1.0.1)
# 3. 输入更改描述

详细操作示例：

$ npx changeset
🦋  Which packages would you like to include?
◯ changed packages
  ◉ @nomicfoundation/hardhat-verify  # 用空格选中
◯ unchanged packages
  ◯ hardhat
  ◯ 其他包...

🦋  Which packages should have a major bump? · No items selected
🦋  Which packages should have a minor bump? · @nomicfoundation/hardhat-verify
🦋  Please enter a summary for this change:
🦋  Summary › Add proxy support for contract verification in restricted networks

🦋  === Summary of changesets ===
🦋  minor:  @nomicfoundation/hardhat-verify

🦋  Is this your desired changeset? (Y/n) › Y

方法二：手动创建

# 创建 changeset 文件
cat > .changeset/add-proxy-support.md << 'EOF'
---
"@nomicfoundation/hardhat-verify": minor
---

Add proxy support for contract verification in restricted network environments. 
Fixes ECONNREFUSED errors when accessing Etherscan API behind proxy settings.
EOF

版本类型选择指南

Major 版本 (破坏性更改)

// 示例：删除了公共 API
// 之前
export function verifyContract(address) { ... }

// 之后 - 破坏性更改
export function verifyContractWithOptions(address, options) { ... }
// verifyContract 函数被删除

Minor 版本 (新功能，向后兼容)

// 示例：添加新功能，保持兼容
// 之前
export function verifyContract(address) { ... }

// 之后 - 向后兼容
export function verifyContract(address, options = {}) { ... }
// 原有调用方式仍然有效

Patch 版本 (bug修复)

// 示例：修复bug，不影响API
// 之前
function verifyContract(address) {
    return fetch(url).then(response => response.json())  // 缺少错误处理
}

// 之后 - 修复bug
function verifyContract(address) {
    return fetch(url)
        .then(response => {
            if (!response.ok) throw new Error('Network error')
            return response.json()
        })
}

提交 Changeset

# 添加 changeset 文件到 git
git add .changeset/

# 提交
git commit -m "Add changeset for proxy support feature"

# 推送
git push origin feature/your-branch

Changeset 文件格式

---
"package-name-1": minor
"package-name-2": patch
---

描述这次更改的内容。这些内容会出现在 changelog 中。

可以包含多行描述，支持 markdown 格式：
- 新增功能A
- 修复问题B
- 改进性能C

多包更新示例

---
"@nomicfoundation/hardhat-verify": minor
"@nomicfoundation/hardhat-utils": patch
---

Add proxy support across verification tools

- hardhat-verify: Add proxy detection and dispatcher creation
- hardhat-utils: Fix proxy URL parsing helper function

常见问题和解决方案

Git 相关问题

1. 推送被拒绝

# 错误信息
! [rejected] main -> main (fetch first)

# 解决方案：先拉取远程更改
git pull origin main
# 或者强制推送（谨慎使用）
git push --force-with-lease origin main

2. 合并冲突

# 当出现合并冲突时
git status  # 查看冲突文件

# 手动编辑冲突文件，解决冲突标记：
# <<<<<<< HEAD
# 你的更改
# =======
# 他人的更改
# >>>>>>> branch-name

# 解决后添加文件
git add conflicted-file.js
git commit -m "Resolve merge conflict"

3. 分支同步问题

# 同步上游仓库的最新更改
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# 将主分支的更改合并到你的功能分支
git checkout feature/your-branch
git merge main

Changeset 相关问题

1. 没有 .changeset 目录

# 错误信息
🦋  error There is no .changeset folder.

# 解决方案：检查是否在项目根目录
cd project-root
ls -la | grep changeset

# 如果确实没有，可能项目不使用 changeset
# 查看项目文档或询问维护者

2. 无法选择包

# 问题：界面显示但无法选择

# 解决方案：
# 1. 使用空格键（不是回车键）选择
# 2. 确保你在正确的项目目录
# 3. 手动创建 changeset 文件

3. 版本类型选择错误

# 如果提交了错误的版本类型
# 可以删除并重新创建
rm .changeset/wrong-changeset.md
npx changeset  # 重新创建

PR 相关问题

1. 测试失败

# 本地运行测试
npm test

# 如果测试失败，修复后重新提交
git add .
git commit -m "Fix failing tests"
git push origin feature/your-branch

2. 代码风格检查失败

# 运行代码格式化
npm run format
# 或
npx prettier --write .

# 运行 lint 检查
npm run lint
# 或
npx eslint . --fix

# 提交格式化后的代码
git add .
git commit -m "Fix code style issues"
git push origin feature/your-branch

3. PR 被要求修改

# 在同一分支继续开发
# 不需要创建新的 PR
git add .
git commit -m "Address review feedback"
git push origin feature/your-branch

# PR 会自动更新

最佳实践总结

提交信息规范

# 好的提交信息
git commit -m "Add proxy support for contract verification

- Detect HTTP_PROXY environment variable
- Create proxy agent for fetch requests  
- Add tests for proxy functionality
- Update documentation"

# 避免的提交信息
git commit -m "fix bug"
git commit -m "update"
git commit -m "changes"

分支管理

# 保持分支名称清晰
feature/proxy-support        # ✅ 好
bugfix/verification-timeout  # ✅ 好
docs/api-examples            # ✅ 好

my-changes                   # ❌ 不清晰
test                         # ❌ 太模糊
fix                          # ❌ 不具体

代码审核准备

• ✅ 确保所有测试通过
• ✅ 代码风格符合项目规范
• ✅ 添加必要的测试用例
• ✅ 更新相关文档
• ✅ 提交信息清晰明确
• ✅ 处理所有 TODO 和 FIXME
• ✅ 删除调试代码和注释

这份指南涵盖了从个人项目到开源贡献的完整流程，包括详细的 Changeset 使用说明。按照这个指南操作，你就能够顺利参与任何开源项目的贡献了！