从零到上线：Python 开源项目的规范化开发与发布指南

1.5 依赖管理

• requirements.txt 适合轻量级场景

pip freeze > requirements.txt

requirements.txt（生产）

fastapi>=0.100.0
pydantic>=2.0.0

requirements-dev.txt（开发）

pytest>=7.0.0
black>=23.0.0
ruff>=0.1.0

1.6 项目配置文件

• 现代 Python 项目推荐使用 pyproject.toml 统一管理构建与工具配置
• 一个完整的 TOML 配置文件应该包含如下：

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.backends.legacy:build"

[project]
name = "my-project"
version = "0.1.0"
description = "项目描述"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [{ name = "Your Name", email = "[email protected]" }]
dependencies = [
 "fastapi>=0.100.0",
]

[project.urls]
Homepage = "https://github.com/yourname/my-project"

[tool.ruff]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]

二、开发阶段：协作流程规范

2.1 Git 分支模型

• Git 分支模型带来的好处有：并行开发，版本管理、隔离风险等，是现在最常用的多人协作开发模型
• 主要的分支策略有两种：Git Flow、Github Flow
• Github Flow：feature/xxx -> develop -> main

### 关联远程仓库 (你的 github 项目仓库)
git remote add origin https://github.com/yourname/my-project.git
### 指定为主分支
git branch -M main
### 推送分支
git push -u origin main

### 创建 develop 分支
git checkout -b develop
git push -u origin develop
### 开发新功能，切出其他分支
git checkout -b feature/add-login develop
### 开发完成后
git push origin feature/add-login

• 在 Github 上发起 PR，也称提 PR

2.2 分支保护规则

在 Github 的 Settings → Branches → Branch protection rules 对 main 分支设置

2.3 CI/CD 自动化

• 全称为持续集成/持续交付
• CI 主要为自动化测试和构建，开发者每次提交代码都会自动触发：单元测试、集成测试、代码风格检查、打包构建等
• CD 主要为自动化部署到类生产环境，运行更深层次的测试：性能测试、安全扫描等
• 一般来说 PR 合并前 CI 必须通过，防止问题代码进入主干

2.4 PR 规范

• PR 包括每次 commit 的标题建议遵循 Conventional Commits 格式：

feat: 添加用户登录功能
fix: 修复 token 过期未刷新问题
docs: 更新 API 文档
refactor: 重构数据库连接池逻辑

三、发布阶段：版本管理与 PyPI 上传

3.1 语义化版本号

• 通俗来讲就是如何命名每次发布的版本，格式为 MAJOR.MINOR.PATCH

3.2 发布流程

# 1. 确保 main 分支代码最新
git checkout main
git pull origin main
# 2. 打 Tag
git tag v0.1.1
git push origin v0.1.1
# 3. 构建分发包
rm -rf dist/ build/
python -m build # 会生成 dist/my_project-0.1.1.tar.gz 和 .whl 文件
# 4. 上传到 PyPI
twine upload dist/* # 首次需要配置 API Token(需 two factors 验证)

3.3 发布信息维护

• 每次发布前需要更新 CHANGELOG.md，记录版本变更：

## [v0.1.1] - 2025-02-25
### Fixed
- 修复并发请求下的竞态条件问题

## [v0.1.0] - 2025-01-10
### Added
- 初始版本发布
- 支持基本的 CRUD 操作

• 或者在 Releases 界面直接编辑

四、维护阶段：长期运维建议

• Issue 模版：在 .github/ISSUE_TEMPLATE/ 下配置 Bug Report 和 Feature Request 模版、规范用户反馈。
• 依赖更新：定期执行 pip list --outdated 或接入 Dependabot 自动检测依赖安全漏洞。
• 文档站：使用 MkDocs + GitHub Pages 搭建在线文档，与代码仓库联动自动部署。