Git与GitHub实战：从零开始为CircuitPython开源项目贡献代码

1. 项目概述与核心价值

如果你玩过CircuitPython，或者用过任何Adafruit的硬件，大概率会接触到他们托管在GitHub上的开源代码库。你可能发现了一个小bug，或者想给某个库增加一个酷炫的新功能，心里琢磨着：“这个我能修”或者“这个功能加上去肯定很棒”。但当你点开GitHub上那个满是英文和奇怪术语的页面，准备提交代码时，瞬间就被“Fork”、“Clone”、“Branch”、“PR”这些词给整懵了。Git的操作界面是命令行，GitHub的网页流程对新手也不够友好，明明想为社区做点贡献，却感觉被一道无形的技术门槛挡在了外面。

这种感觉我太熟悉了。几年前我刚接触开源贡献时，光是搞明白怎么把本地改好的代码“送”到远端的项目里，就折腾了好几天。网上的教程要么太零散，只讲单个命令；要么太理论，看完还是不知道下一步该点哪里。Git和GitHub是现代开源协作的“普通话”，不会说这门“语言”，你就很难真正参与到像CircuitPython这样充满活力的开源生态中去。本文的目的，就是充当你的“方言翻译”和“实地导游”。我将以向Adafruit CircuitPython库提交一个修复为例，手把手带你走完从“我有一个想法”到“代码被合并进主项目”的完整闭环。这不是一个简单的命令列表，而是一个我用了多年、踩过无数坑后沉淀下来的实战工作流。你会学到为什么每个步骤是必要的，操作时有哪些“坑”需要提前避开，以及当流程卡住时该如何排查。无论你是想修复CircuitPython库里的一个拼写错误，还是为传感器驱动添加新的方法，这套流程都是通用的。

2. 前期准备与环境搭建

在开始写任何代码之前，我们需要确保手头的“工具”是齐全且配置正确的。这就像木匠开工前要磨好刨子和凿子一样，基础打牢了，后续操作才能顺畅。

2.1 核心工具安装与基础配置

首先，你需要在电脑上安装Git。这不是一个可选项，而是必须项。你可以从Git的官方网站下载对应操作系统的安装包。安装过程基本就是一路“下一步”，但有一个关键点需要注意：在Windows系统上，安装程序会询问你选择哪种默认的终端（Terminal）。这里我强烈建议选择“Use Windows‘ default console window”或者安装程序提供的Git Bash。不要选择“Use the OpenSSH”相关的选项，除非你非常清楚自己在做什么。Git Bash提供了一个更接近Linux/macOS环境的命令行体验，兼容性更好，能避免很多因路径或换行符引起的诡异问题。

安装完成后，打开终端（Windows上是Git Bash或CMD/PowerShell，macOS是Terminal，Linux是任意终端模拟器），我们需要进行最基础的身份配置。这相当于给你的每一次代码提交“签名”。

git config --global user.name "你的GitHub用户名" git config --global user.email "你注册GitHub的邮箱"

这两行命令的作用是全局设置提交者的姓名和邮箱。请务必使用你GitHub账号关联的邮箱，这样你在GitHub上的贡献图表才会被正确记录。--global参数意味着这个配置对这台电脑上所有的Git仓库都生效，一劳永逸。

接下来，你需要一个GitHub账号。如果还没有，去GitHub官网注册一个，这个过程很简单。拥有账号后，我建议你立即设置SSH密钥认证，这能让你在推送代码时免去反复输入密码的麻烦。在终端中运行ssh-keygen -t ed25519 -C “你的邮箱”，然后一路回车接受默认设置。完成后，用cat ~/.ssh/id_ed25519.pub命令打印出公钥内容，复制它，并粘贴到GitHub网站的 Settings -> SSH and GPG keys 页面中。完成这一步后，你与GitHub服务器之间的通信就建立了一条安全便捷的“专属通道”。

2.2 理解核心概念：仓库、分支与远程

在动手之前，花几分钟理解三个核心概念，能让你后面的操作不再是机械记忆，而是“知其所以然”。

1. 仓库（Repository， 简称Repo）：你可以把它想象成一个项目的“超级版本存档柜”。它不仅仅保存项目当前的所有文件，还完整记录了每一个文件从创建到现在，每一次是谁、在什么时候、改了什么的全部历史。CircuitPython的每一个库，在GitHub上都是一个独立的仓库。

2. 分支（Branch）：这是Git最强大的功能之一。想象主分支（main， 过去也叫master）是一条笔直向前的时间线，记录了项目官方发布的稳定版本。当你要修改或添加功能时，绝对不应该直接在这条主时间线上动手。正确的做法是，从主时间线的某个点“岔开”一条属于自己的、独立的时间线，这就是创建分支。你在这条分支时间线上的所有实验、修改、甚至搞砸的操作，都不会影响到主时间线。完成后，你可以申请将你的这条分支时间线“合并”回主时间线。这保证了主干的稳定，同时支持了无限的并行开发。

3. 远程（Remote）：你的电脑上的仓库叫“本地仓库”。GitHub服务器上的仓库叫“远程仓库”。一个本地仓库可以关联多个远程仓库，并给它们起别名以便区分。最典型的两个别名是：

   • origin：通常指向你自己在GitHub上复制的那个仓库（即你的Fork）。
   • upstream：通常指向原始的项目仓库（例如adafruit/Adafruit_CircuitPython_Some_Library）。 这种设计让你可以轻松地从原始项目同步更新（从upstream拉取），同时将自己的工作推送到自己的副本（推送到origin），最后再向原始项目发起合并请求。

注意：很多教程会教你把原始仓库的远程别名设为upstream。但在实际协作中，特别是当你同时参与多个不同组织的项目时，我推荐一个更清晰的做法：用项目所有者的GitHub ID作为别名。例如，对于Adafruit的仓库，我用adafruit；对于某个个人开发者的仓库，我就用他的用户名。这样，当你同时打开多个终端标签页操作不同项目时，看一眼远程别名就能立刻反应过来当前在操作谁的项目，极大减少了误操作的风险。下文将沿用这个实践。

3. 工作流第一步：分叉与克隆

现在，假设我们找到了一个想贡献的CircuitPython库，比如Adafruit_CircuitPython_DHT。我们的贡献之旅将从“分叉”开始。

3.1 创建你的项目副本（Fork）

登录你的GitHub账号，在浏览器中导航到目标仓库的页面。在页面的右上角，你会看到一个醒目的“Fork”按钮。点击它。

这时，GitHub会弹出一个对话框，询问你要将仓库分叉到哪个账户（通常就是你自己的账户），以及是否“仅复制默认分支”。这里有一个关键选择：对于CircuitPython这类项目，我建议你取消勾选“Copy themainbranch only” 这个选项。这意味着你将复制该仓库的所有分支，而不仅仅是当前的主分支。虽然大部分时候你只会在main分支上工作，但有些项目可能会用其他分支进行重大版本的开发或测试。拥有全部分支能让你在需要时切换到任何工作上下文，避免未来可能出现的兼容性问题。

点击“Create fork”后，稍等片刻，页面会自动跳转到一个全新的仓库地址，格式是https://github.com/你的用户名/Adafruit_CircuitPython_DHT。恭喜，你现在拥有了一个属于你自己的、与原始仓库完全独立的副本。你可以在这个副本里为所欲为，而不会影响到原始项目。

3.2 将副本下载到本地（Clone）

仓库在云端准备好了，接下来需要把它“下载”到你的电脑上，以便进行编辑。这个下载过程在Git中称为“克隆”（Clone）。

在你的副本仓库页面上，找到绿色的“Code”按钮。点击它会显示一个下拉框，里面有一个以https://github.com...或git@github.com...开头的URL。如果你配置了SSH密钥，强烈建议使用以git@开头的SSH URL，这样更安全便捷。点击URL旁边的复制图标，将其复制到剪贴板。

现在，打开你的终端。首先，为你所有的Git项目创建一个专门的目录是个好习惯，比如~/projects或~/repos。使用cd命令进入这个目录。

接下来执行克隆命令。如前所述，我们将为这个远程仓库设置一个清晰的别名。命令格式如下：

git clone -o 你的GitHub用户名 仓库的SSH或HTTPS地址

例如：

git clone -o tannewt git@github.com:tannewt/Adafruit_CircuitPython_DHT.git

这个命令做了三件事：

1. 将远程仓库（你的Fork）完整地下载到本地，创建一个同名文件夹。
2. 将这个远程仓库的别名设置为tannewt（而不是默认的origin）。
3. 自动将本地仓库的当前分支与远程的main分支关联起来。

命令执行成功后，使用cd Adafruit_CircuitPython_DHT进入这个新创建的本地仓库目录。

3.3 添加上游远程源

你的本地仓库目前只认识你的Fork（别名tannewt）。为了能随时获取原始项目（Adafruit官方）的最新更新，我们需要添加第二个远程源。

回到浏览器，打开原始的Adafruit仓库页面（adafruit/Adafruit_CircuitPython_DHT）。同样复制它的SSH或HTTPS URL。

在终端中，确保你还在本地仓库的目录下，然后运行：

git remote add adafruit git@github.com:adafruit/Adafruit_CircuitPython_DHT.git

这里，adafruit就是我们给原始仓库起的别名。现在，你的本地仓库就认识两个“远程”了：tannewt（你的Fork）和adafruit（原始项目）。你可以用git remote -v命令来查看所有已配置的远程仓库及其对应的URL，确认添加成功。

4. 在正确的分支上开展工作

一切准备就绪，是不是可以打开编辑器开始改代码了？还差一步。我们必须确保在一个独立的分支上进行修改。

4.1 为什么一定要用分支？

直接在主分支（main）上修改代码是贡献流程中的大忌，原因有三：

1. 污染主线：你的实验性代码可能会破坏项目当前的可工作状态。
2. 难以管理：如果你同时想尝试两种不同的解决方案，或者修复多个不相关的bug，所有修改都会混杂在一起，像一团乱麻。
3. 同步困难：当原始项目的主分支有更新时，你直接修改过的本地主分支会很难同步这些更新，极易产生冲突。

因此，我们的黄金法则是：永远在一个专门为某个特定任务创建的新分支上工作。

4.2 更新本地主分支

在创建新分支之前，最好先确保你的本地主分支是基于原始项目最新的代码。这就像在动手盖房子之前，先确认地基是最新、最牢固的图纸。

首先，切换到本地的主分支：

git checkout main

然后，从原始项目的远程仓库（adafruit）获取最新的数据。fetch命令只会下载更新，不会自动合并到你的当前分支。

git fetch adafruit

最后，将原始项目主分支的最新内容合并到你本地的主分支：

git merge adafruit/main

如果adafruit/main比你本地的main更新，你会看到一些文件被更新的提示。现在，你的本地main分支就和官方仓库完全同步了。

4.3 创建并切换至功能分支

现在，我们从这块干净的“地基”上创建属于我们自己的工作分支。分支的命名最好具有描述性，让人一眼就知道这个分支是做什么的。例如，如果你要修复DHT传感器读取超时的问题，可以命名为fix-dht-read-timeout。

创建并立即切换到新分支的命令是：

git checkout -b fix-dht-read-timeout

执行后，终端通常会提示 “Switched to a new branch ‘fix-dht-read-timeout‘”。现在，你所有的后续修改都将在这个分支上进行，与main分支完全隔离。

5. 代码提交前的质量守门员：pre-commit

在CircuitPython等许多现代开源项目中，代码风格和基本质量不是靠人工review时唠叨来保证的，而是通过自动化工具在提交前自动检查和修复。pre-commit就是这样一个框架，它能在你执行git commit命令的瞬间，自动运行一系列检查（如代码格式、语法错误等）。

5.1 安装与配置 pre-commit

首先，你需要在电脑上全局安装pre-commit工具（通常只需一次）：

pip install pre-commit

注意：如果你在Ubuntu 22.04或类似的Debian系统上遇到关于Python环境健康的错误，可能需要一个变通方案。在你的~/.bashrc或~/.bash_aliases文件末尾添加一行export SETUPTOOLS_USE_DISTUTILS=stdlib，然后重启终端或运行source ~/.bashrc。但请注意，在Ubuntu 24.04或Debian Bookworm及更高版本上，不要设置这个环境变量，否则可能导致pip install失败。

安装好全局工具后，你需要为每一个克隆到本地的仓库安装其特定的钩子（hooks）。进入你的项目目录，运行：

pre-commit install

这个命令会在当前仓库的.git/hooks目录下安装一系列脚本。之后，每当你执行git commit时，这些脚本就会自动触发，对你即将提交的文件运行项目预设的检查（例如用black格式化Python代码，用pylint进行静态分析等）。

5.2 pre-commit 的工作流程与应对

当你修改了代码并执行git commit -m “...”后，pre-commit会自动运行。可能会出现以下几种情况：

1. 全部通过：检查工具没有发现问题，提交成功创建。这是最理想的情况。
2. 自动修复并提示：大多数检查工具（如black,isort）在发现格式问题时，会自动修复你的文件。然后pre-commit会报错，并提示你“文件已被修改”。此时，你需要用git status查看，会发现那些被自动修复的文件处于“已修改但未暂存”的状态。你只需再次执行git add .将这些修复后的文件加入暂存区，然后重新执行git commit即可。这个过程可能会重复几次，直到所有检查都通过。
3. 发现必须手动修复的错误：有些错误（如复杂的语法错误、未定义的变量）无法自动修复。pre-commit会报错并停止提交，你需要根据错误信息手动修改代码，然后重新add和commit。

你也可以在任何时候手动运行所有检查，命令是：

pre-commit run --all-files

养成在提交前运行pre-commit的习惯，能极大提高你的代码质量，并减少在后续Pull Request环节因格式问题被要求修改的几率。这是成为专业贡献者的重要一步。

6. 代码修改与提交的艺术

现在，你可以在fix-dht-read-timeout分支上安心地修改代码了。使用你喜欢的编辑器（如VSCode、PyCharm、Vim等）打开需要修改的文件。

6.1 小步快跑，频繁提交

完成一部分逻辑修改后（比如，你刚刚实现了一个修复超时读取的新函数），不要等到所有代码都写完再提交。Git的提交（Commit）应该“小步快跑”，每个提交都应该是一个完整、独立、可解释的变更集。

例如：

• 不好的提交：“修复了DHT库的一堆问题”。（这太模糊了，包含了多个不相关的修改。）
• 好的提交：“为DHT.read()方法增加重试机制”。（清晰、单一的目的。）
• 更好的提交：“修复DHT.read()在树莓派Pico W上因中断导致的读取失败”。（具体到场景和原因。）

这样做的好处是：首先，它为你创建了丰富的“还原点”，如果后续修改引入了新bug，你可以轻松回退到任何一个工作状态。其次，清晰的提交历史就像一篇详细的开发日志，能让代码审查者（和你未来的自己）一目了然地理解你的开发思路。

6.2 使用 git status 和 git diff 掌控全局

在每次操作前，运行git status是你的第一要务。这个命令会告诉你当前仓库的状态：

• 你在哪个分支上？
• 有哪些文件被修改了但还没准备提交？（Changes not staged for commit）
• 有哪些文件已经暂存，等待提交？（Changes to be committed）
• 有没有未跟踪的新文件？（Untracked files）

在git add之前，我强烈建议使用git diff命令。它会以高亮对比的方式，显示出自上次提交以来，你具体修改了哪些代码行（绿色以+开头的是新增，红色以-开头的是删除）。这是你最后一次在提交前仔细检查代码变更的机会，确保你没有误删有用的代码，或者引入了调试用的print语句。

6.3 标准的提交循环

一个完整的、小规模的修改和提交流程通常如下：

1. 修改代码：编辑adafruit_dht.py文件。
2. 检查状态：git status。看到adafruit_dht.py出现在 “Changes not staged for commit” 下。
3. 查看差异：git diff adafruit_dht.py。仔细确认修改是否正确。
4. 暂存文件：git add adafruit_dht.py。或者，如果你想暂存所有已修改的文件，用git add .。
5. 再次检查状态：git status。此时文件应移动到 “Changes to be committed” 下。
6. 提交：git commit -m “为DHT.read()增加2次重试逻辑以应对偶发读取失败”。

重复这个循环，直到你完成了这个分支上的所有预定工作。记住，提交信息（commit message）的第一行应尽量保持在50个字符以内，作为一个简洁的摘要。如果必要，可以在第一行后空一行，然后写更详细的正文。

7. 推送更改与发起拉取请求

当你在本地分支上完成了所有工作，并进行了若干次满意的提交后，就该将你的成果分享给世界，并申请合并到原始项目了。

7.1 推送到你的远程分支

首先，确保你的工作区是干净的（运行git status应显示 “nothing to commit, working tree clean”）。然后，将你的本地分支推送到你的GitHub Fork（即origin， 但我们之前将其别名设为了你的用户名，例如tannewt）。

git push tannewt fix-dht-read-timeout

这条命令的意思是：“请将本地的fix-dht-read-timeout分支，推送到远程仓库tannewt下，并在远程也创建一个同名的分支。” 这是你第一次将这个分支推送到远程，Git可能会提示你用--set-upstream来建立追踪关系，按照它的提示操作即可，或者直接使用git push -u tannewt fix-dht-read-timeout，-u参数就是用来设置上游关联的。

推送成功后，刷新你的GitHub Fork页面，你会在分支下拉列表中看到这个新分支，并且点击进去可以看到你所有的提交。

7.2 在GitHub上创建拉取请求

现在，你的代码已经安全地存在于GitHub上了。接下来，你需要告诉原始项目的维护者：“嘿，我修好了一个bug，请看看是否可以把我的修改合并到你们的项目里。” 这个“申请”就是拉取请求（Pull Request， 简称PR）。

有两种常见的方式创建PR：

1. 从你的Fork页面发起（推荐给新手）：在你的Fork仓库页面，GitHub经常会检测到你刚刚推送了新分支，并显示一个醒目的 “Compare & pull request” 按钮。点击它。
2. 从原始仓库页面发起：导航到原始项目仓库（如adafruit/Adafruit_CircuitPython_DHT），点击 “Pull requests” 标签页，然后点击绿色的 “New pull request” 按钮。在比较页面，你需要将 “base repository” 设置为原始仓库的main分支，将 “head repository” 设置为你自己的Fork下的fix-dht-read-timeout分支。

无论哪种方式，你都会进入创建PR的页面。这里有几个关键部分需要认真填写：

• 标题（Title）：这是PR的脸面。要简洁、清晰地概括这个PR做了什么。例如：“Fix intermittent read failures in DHT library by adding retry logic”。
• 描述（Description）：详细说明你为什么要做这个修改。可以包括：
  • 这个PR解决了什么问题？（可以关联一个GitHub Issue的编号，如Fixes #123）
  • 你是如何解决的？（简述技术方案）
  • 你做了哪些具体的更改？
  • 测试过吗？如何测试的？（例如：“在Raspberry Pi Pico W上使用DHT22传感器进行了超过100次连续读取测试，成功率从~85%提升至100%。”）
  • 附上测试截图或数据，说服力会更强。
• 审查者（Reviewers）：可以@项目的主要维护者（如果你知道他们的GitHub用户名），邀请他们来审查代码。

填写完毕后，点击 “Create pull request”。你的PR就正式进入了项目的待审查队列。

8. 代码审查与协作流程

创建PR不是终点，而是另一个重要阶段的开始：代码审查（Code Review）。这是开源协作中保证代码质量的核心环节。

8.1 理解PR的界面与状态

打开你的PR页面，你会看到几个主要区域：

• 对话（Conversation）：这是主要的讨论区，审查者会在这里发表总体评论，你也可以在这里进行解释和讨论。
• 提交列表（Commits）：显示了这个PR包含的所有提交，点击可以查看每次提交的详细变更。
• 文件变更（Files changed）：这是审查的核心区域。它以对比视图（Diff）的形式，展示了你的分支与目标分支（通常是main）之间所有文件的差异。审查者会在这里对具体的代码行发表评论。
• 检查状态（Checks）：这里会显示自动化测试（如CI/CD）的运行结果。对于CircuitPython项目，这通常包括pre-commit检查、单元测试、文档构建等。在请求审查前，最好确保所有检查都已通过（显示绿色对勾）。

8.2 与审查者互动

审查者可能会在“文件变更”页面对某行代码提出疑问（“为什么这里要加这个判断？”）或建议（“这个变量名可以取得更清晰一些”）。这些评论会以对话气泡的形式出现在代码旁。

当审查者提出修改建议时，通常有两种情况：

1. 评论（Comment）：仅仅是询问或建议，你需要手动修改代码。
2. 建议更改（Suggested Change）：审查者可以直接在GitHub界面上提出一个具体的代码修改建议。你可以选择“Commit suggestion”一键采纳这个修改，这会在你的分支上创建一个新的提交。

如何应对审查：

• 保持积极和礼貌。审查的目的是为了提升代码质量，而不是批评你个人。用“谢谢你的建议，我已经修改了”这样的语气回复。
• 对每一个评论都进行回复。即使你只是说“Done”或者贴出修改后的代码片段，也让审查者知道你已经处理了。
• 如果不同意某个建议，礼貌地解释你的理由。技术讨论是健康的。

8.3 根据反馈更新PR

根据审查意见修改代码后，你不需要关闭旧PR再开新的。你只需要：

1. 在本地你的功能分支（fix-dht-read-timeout）上继续修改代码。
2. 完成修改后，按照之前的流程add、commit（提交信息可以写“Address review comments: clarify variable naming”）。
3. 再次推送到你的远程分支：git push tannewt fix-dht-read-timeout。

神奇的是，你这次推送的新提交会自动附加到之前那个已经存在的PR后面。审查者会看到PR被更新了，他们可以继续查看新的变更。

8.4 合并与后续清理

当所有审查意见都被解决，审查者批准（Approve）了你的PR，并且所有自动化检查都通过后，项目的维护者（或者有合并权限的你，如果被授权了）就可以点击“Merge pull request”按钮，将你的分支合并到主项目中。

合并通常有三种方式：

• Create a merge commit：创建一个新的合并提交，保留完整的分支历史。这是最常用的方式，历史清晰。
• Squash and merge：将你PR中的所有提交“压缩”成一个新的提交，然后合并。这可以使主分支的历史更简洁。
• Rebase and merge：将你的提交“变基”到目标分支的最新提交之后，形成一条直线历史。

合并完成后，页面上会显示“Pull request successfully merged and closed”的提示。此时，你的代码已经成为官方项目的一部分了！

合并后的清理工作：

1. 删除远程分支：在PR合并后，GitHub页面通常会有一个“Delete branch”按钮，点击它可以删除你Fork上的这个功能分支。保持仓库整洁。
2. 删除本地分支：回到你的本地终端，切换回main分支：git checkout main。
3. 从原始仓库拉取最新的main（现在包含了你的贡献）：git pull adafruit main。
4. 删除已经合并的本地功能分支：git branch -d fix-dht-read-timeout。
5. （可选）更新你的Fork的main分支：git push tannewt main。

至此，一个完整的开源贡献周期就圆满结束了。

9. 进阶技巧与疑难排解

掌握了基本流程后，一些进阶技巧和常见问题的解决方法能让你更游刃有余。

9.1 保持你的Fork与原始项目同步

你的Fork是一个独立的副本，它不会自动从原始项目（adafruit）获取更新。长期不更新，你的Fork会严重落后，导致未来基于它创建新分支时，可能产生大量冲突。

定期同步的步骤如下：

1. 在本地，确保你在main分支上：git checkout main。
2. 从原始仓库获取最新数据：git fetch adafruit。
3. 将原始仓库的main合并到你的本地main：git merge adafruit/main。（如果出现冲突，需要先解决冲突。）
4. 将更新后的本地main推送到你的Fork：git push tannewt main。

你也可以在GitHub网页端使用“Sync fork”按钮，但通过命令行操作更能理解其原理。

9.2 处理合并冲突

冲突发生在你修改文件的同一区域时，Git无法自动决定该保留谁的修改。例如，你和项目维护者同时修改了同一行代码。

当执行git merge或git pull时如果遇到冲突，Git会标记出冲突的文件。打开这些文件，你会看到类似这样的标记：

<<<<<<< HEAD # 这是你本地分支的修改 retry_count = 3 ======= # 这是远程分支的修改 retry_count = 5 >>>>>>> adafruit/main

你需要手动编辑这个文件，决定最终要保留的代码（比如，经过讨论，决定采用retry_count = 4），并完全删除<<<<<<<、=======和>>>>>>>这些标记行。解决完所有冲突文件后，使用git add .标记它们为已解决，然后执行git commit来完成合并。

9.3 当推送（push）失败时

如果你在git push时收到类似 “failed to push some refs” 的错误，并提示 “Updates were rejected because the remote contains work that you do not have locally”，这通常意味着你的远程分支（比如GitHub上的fix-dht-read-timeout）已经有了你本地没有的提交。这可能发生在你从多台电脑操作同一个分支，或者你通过GitHub网页界面接受了“建议的更改”之后。

不要盲目使用git push --force（强制推送），这会覆盖远程的历史，可能导致他人工作丢失。正确的做法是先拉取（pull）远程的更改，合并到本地，解决可能的冲突，然后再推送。

# 先拉取远程分支的更新到本地 git pull tannewt fix-dht-read-timeout # 解决可能出现的冲突（如果有的话） # ... # 将合并后的结果再次推送 git push tannewt fix-dht-read-timeout

9.4 参与审查：成为积极的社区成员

为别人的PR提供审查（Review）是另一种极有价值的贡献方式。一个好的审查者应该：

• 聚焦于代码，而非个人。
• 明确具体：不要说“这段代码不好”，而要说“这个循环的复杂度是O(n²)，对于大数据集可能性能不佳，可以考虑用字典优化”。
• 不仅指出问题，也提供解决方案或思路。
• 对于明显的拼写错误或格式问题，直接使用“建议更改”功能。
• 及时响应，不要让PR晾在那里太久。

通过审查他人的代码，你能学习到不同的编程风格和解决问题的思路，这也是提升自己技术能力的绝佳途径。

向CircuitPython或任何开源项目贡献代码，最初看起来步骤繁多，但一旦你完整走过几遍这个流程，它就会变成肌肉记忆。这套基于Git和GitHub的工作流，是当今全球开源开发者协作的通用语言。每一次成功的PR合并，不仅是对项目的改进，也是你个人在开发者社区中留下的坚实足迹。从修复一个错别字开始，逐步到增加示例代码，再到实现新功能，每一步都在让开源生态变得更好。现在，你已经掌握了这门“语言”，是时候去寻找一个感兴趣的Issue，或者将你自己的想法变成代码，开启你的第一次贡献了。如果在实践中遇到任何本指南未覆盖的具体问题，CircuitPython社区的Discord和论坛永远是寻求帮助的好地方。