GitHub 对很多开发者来说不是“存代码的网站”，而是项目从个人电脑走向协作的入口。一个本地 Python 项目，只要放进远程仓库、推送到 GitHub，再用 Issues 管理任务和讨论，就具备了最小但完整的团队协作形态。
GitHub 仓库到底解决什么问题
本地 Git 仓库记录的是你机器上的提交历史。GitHub 上的远程仓库则多做了三件事：
- 让代码有一个团队都能访问的中心位置。
- 让提交、分支、变更记录可以被审查和追踪。
- 让 bug、需求、讨论通过 Issues 留下上下文。
这也是为什么“会 git commit”还不等于“会用 GitHub 协作”。Git 负责版本历史，GitHub 负责把版本历史放到一个可协作的空间里。
创建远程仓库：先别急着上传所有东西
在 GitHub 上创建新仓库时，通常需要决定几个基础选项：
- 仓库名：建议和项目目录一致，例如
hello-python-github。 - 可见性：练习项目可以选 Public；公司代码、私有实验应选 Private。
- README：如果本地项目已经有 README，可以不让 GitHub 自动生成，避免第一次推送时出现历史冲突。
.gitignore：Python 项目应忽略虚拟环境、缓存、构建产物等文件。
可以这样实践：先在本地准备一个最小 Python 项目，再推送到 GitHub。下面的命令假设你已经在 GitHub 创建了一个空仓库，并拿到了远程地址，例如 https://github.com/YOUR_NAME/hello-python-github.git。
mkdir hello-python-github
cd hello-python-github
cat > app.py <<'PY'
def greet(name: str) -> str:
return f"Hello, {name}!"
if __name__ == "__main__":
print(greet("GitHub"))
PY
cat > README.md <<'MD'
# hello-python-github
A tiny Python project used to practice pushing code to GitHub.
## Run
```bash
python app.py
MD
cat > .gitignore <<'TXT' pycache/ *.py[cod] .venv/ venv/ dist/ build/ .env TXT
python app.py
运行后应看到：
```bash
Hello, GitHub!
如果你使用 Windows PowerShell，可以手动创建 app.py、README.md 和 .gitignore，文件内容保持一致即可。
把本地项目推送到 GitHub
项目文件准备好后，用 Git 初始化仓库、提交代码，并绑定 GitHub 远程仓库。
把下面命令里的 YOUR_NAME 和仓库名改成你自己的：
git init
git add .
git commit -m "Initial Python project"
git branch -M main
git remote add origin https://github.com/YOUR_NAME/hello-python-github.git
git push -u origin main
这里有几个容易踩坑的点：
git add .会把当前目录下未忽略的文件都加入暂存区，所以.gitignore要先写好。git branch -M main是把当前分支命名为main，和 GitHub 默认分支习惯保持一致。git push -u origin main里的-u会建立本地main和远程origin/main的跟踪关系，之后可以直接用git push。
推送完成后，刷新 GitHub 仓库页面，应该能看到 app.py、README.md 和 .gitignore。
用 Issues 把协作变成可跟踪的工作
代码上传只是开始。多人协作时，真正容易混乱的是“谁在做什么、为什么改、什么时候完成”。GitHub Issues 可以把这些信息放在项目旁边，而不是散落在聊天记录里。
一个好的 Issue 不只是标题。它至少应该包含：
- 现象或目标：发生了什么，或者希望实现什么。
- 复现步骤或验收条件：怎样判断问题存在，怎样判断任务完成。
- 相关上下文：日志、截图、文件路径、版本信息。
例如，可以创建一个 Issue：
Title: Add command-line name argument
## Goal
`app.py` currently always prints `Hello, GitHub!`. Allow users to pass a name from the command line.
## Acceptance Criteria
- `python app.py Alice` prints `Hello, Alice!`
- `python app.py` still prints `Hello, GitHub!`
- README includes the new usage example
拿到这个 Issue 后，开发者可以创建分支修改代码：
git checkout -b feature/cli-name
可以这样改造 app.py：
import sys
def greet(name: str) -> str:
return f"Hello, {name}!"
if __name__ == "__main__":
name = sys.argv[1] if len(sys.argv) > 1 else "GitHub"
print(greet(name))
本地验证：
python app.py
python app.py Alice
提交并推送分支：
git add app.py README.md
git commit -m "Add command-line name argument"
git push -u origin feature/cli-name
之后可以在 GitHub 上打开 Pull Request，并在描述里关联 Issue，例如写 Closes #1。合并后，GitHub 会自动关闭对应 Issue。这种连接让需求、代码变更和结果形成一条线。
协作时要守住的边界
GitHub 的流程很轻，但不代表可以随意推送。小团队也建议遵守几条简单规则：
main分支保持可运行，不把半成品直接推上去。- 每个 Issue 对应一个清晰任务，避免一个 Issue 塞进多个无关目标。
- 分支名表达意图，例如
fix/readme-typo、feature/cli-name。 - Pull Request 描述说明“改了什么”和“怎么验证”。
- 不要提交密钥、
.env、数据库文件、虚拟环境目录。
GitHub 的价值不在于按钮多，而在于它把代码、任务和讨论放在同一个工作台上。对一个 Python 项目来说，先掌握“创建远程仓库、推送本地代码、用 Issues 管理协作”这条主线，就已经能支撑大多数日常开发场景。