Starlette 贡献指南:从提交 Issue 到合并 PR 的完整开发者工作流

原创2026-09-22 20:50:171,684 阅读
文章标签:后端Web框架异步编程WebSocketAPI设计

Starlette 贡献指南:从提交 Issue 到合并 PR 的完整开发者工作流

Starlette 是一个轻量级 ASGI 框架,它的演进离不开社区贡献。本文基于 docs/contributing.md 整理,覆盖参与贡献的全部环节:从通过 Discussion 提交 Bug 报告与功能想法,到 fork 仓库搭建本地开发环境、运行测试与代码检查、编写文档,再到读懂 CI 失败原因,乃至维护者发布新版本的完整流程。读完本文,你将掌握 Starlette 项目标准化的开发工作流,能直接上手提交高质量 PR。

参与贡献的多种方式

Starlette 欢迎任何形式的贡献,并非只有提交代码才算参与。官方文档列出的方式包括:

  • 试用 Starlette 并报告发现的问题:Bug 报告是项目质量的第一道防线;
  • 实现新功能:从仓库中标注了 "good first issue" 的 Issue 入手,适合初次贡献者;
  • Review 他人的 Pull Request:代码评审同样是高价值的贡献;
  • 编写文档:完善 docs/ 目录下的文档页面;
  • 参与讨论:在仓库 Discussion 中发表意见、解答疑问。

报告 Bug 与提出功能建议:从 Discussion 开始

Starlette 的贡献流程有一个明确原则:任何贡献通常都从一次 Discussion 开始,而不是直接提交 Issue。

  • 发现疑似 Bug,可以在 Discussion 中发起 "Potential Issue" 讨论;
  • 有功能想法,可以发起 "Ideas" 讨论。

维护者会根据讨论内容判断是否需要升级为正式的 Issue,或者是否值得提交 Pull Request。这种先讨论、后行动的模式,可以避免重复劳动和无效 PR。

如果最终需要报告 Bug,文档要求尽可能提供完整信息:

  • OS 平台;
  • Python 版本;
  • 已安装的依赖及其版本(通过 python -m pip freeze 输出);
  • 复现问题的代码片段;
  • 错误堆栈(traceback)。

同时应遵循最小复现原则:把示例尽可能缩减为能复现问题的最简代码,这能大幅加速定位与修复。

搭建本地开发环境

要开始开发 Starlette,首先在 GitHub 上 fork 仓库,然后克隆自己的 fork(将 YOUR-USERNAME 替换为你的 GitHub 用户名):

$ git clone https://github.com/YOUR-USERNAME/starlette

进入目录并安装项目及依赖:

$ cd starlette
$ scripts/install

scripts/install 实际做了什么

查看 scripts/install 的源码,它的核心只有一行:

#!/bin/sh -e
set -x
uv sync --frozen

即使用 uv 锁定的版本安装,不重新解析依赖树——这保证了所有贡献者与 CI 环境拿到完全一致的依赖。项目的 Python 版本要求为 >=3.10(见 pyproject.toml),开发依赖集中在 dev 与 docs 两个依赖组中,包含 ruff、mypy、pytest、coverage、mkdocstrings 等工具链。

测试:scripts/test

项目用自定义 shell 脚本统一驱动测试、lint 和文档构建。运行全部测试:

$ scripts/test

scripts/test 会把所有额外参数原样透传给 pytest(具体用法见 pytest 官方文档)。例如只跑某一个测试文件:

$ scripts/test tests/test_applications.py

由于当前仓库的测试文件命名是复数形式,也可以传入目录或具体用例,例如:

$ scripts/test tests/middleware/          # 运行中间件相关全部测试
$ scripts/test tests/test_routing.py      # 运行路由相关测试

scripts/test 的完整执行链

查看 scripts/test 的源码,它的行为比表面更丰富:

#!/bin/sh
set -ex

if [ -z $GITHUB_ACTIONS ]; then
    scripts/check
fi

uv run coverage run -m pytest $@

if [ -z $GITHUB_ACTIONS ]; then
    scripts/coverage
fi

可以拆解为三步:

  1. 非 CI 环境下先跑 scripts/check:本地执行时先做同步版本、格式、类型、lint 全量检查,确保提交前代码达标;在 GitHub Actions 中(GITHUB_ACTIONS 环境变量非空)则跳过,因为 CI 已单独执行检查任务,避免重复耗时;
  2. uv run coverage run -m pytest:用 coverage 包裹 pytest 运行,即测试的同时记录分支覆盖率([tool.coverage.run] 中配置了 branch = true);
  3. 非 CI 环境下再跑 scripts/coverage:检查覆盖率是否达标。

pytest 本身的配置也在 pyproject.toml 中:addopts 启用了 -rXs(显示 skip/xfail 摘要)、--strict-config、--strict-markers,xfail_strict = true,并把未经过滤的 warning 直接升级为异常,保证测试行为严格可控。

代码格式化与静态检查:scripts/lint 与 scripts/check

scripts/lint:自动修复格式与 lint 问题

$ scripts/lint

查看 scripts/lint,它针对 starlette tests 两个目录执行:

uv run ruff format $SOURCE_FILES
uv run ruff check --fix $SOURCE_FILES

即用 ruff 先自动格式化,再自动修复可修复的 lint 问题。注意:scripts/lint 会直接改写代码,运行后请检查 diff 并提交格式化结果。

scripts/check:只读检查(不改动代码)

$ scripts/check

查看 scripts/check,它的检查范围是 starlette tests benchmarks 三个目录,按顺序执行:

./scripts/sync-version
uv run ruff format --check --diff $SOURCE_FILES
uv run mypy $SOURCE_FILES
uv run ruff check $SOURCE_FILES

四步分别对应:

  1. sync-version:校验版本号一致性(见下文"发布新版本");
  2. ruff format --check --diff:检查格式是否合规并输出差异,但不修改文件;
  3. mypy:类型检查,pyproject.toml 中 strict = true,采用最严格的类型约束;
  4. ruff check:静态 lint 检查,行宽限制为 120(pyproject.toml),启用了 E/F/I/FA/UP 等规则组并忽略 UP031。

因此在提交 PR 前的理想操作顺序是:先 scripts/lint 自动修复,再 scripts/check 确认全部通过。

编写文档与本地预览

文档页面位于仓库的 docs/ 目录,docs/contributing.md 本身就是其中之一(由 mkdocs.yml 的 nav 配置挂载在 "Community" 分组下)。修改文档后,可以用如下命令在本地起一个文档站点方便预览:

$ scripts/docs

查看 scripts/docs,它的实现是:

uv run zensical serve

即通过 zensical 启动本地文档服务器。值得一提的是,当前文档构建链路已经从传统 mkdocs 迁移为 zensical 驱动:CI 的文档预览任务同样使用 uv run zensical build --clean(见 .github/workflows/main.yml),mkdocs.yml 中保留了站点导航、主题与 mkdocstrings 插件等配置信息。

排查 CI 失败

提交 Pull Request 后,测试套件会自动运行,结果会显示在 PR 上。一旦失败,应点击 "Details" 链接定位失败原因。当前仓库的 CI 定义在 .github/workflows/main.yml 中:测试任务在 ubuntu-latest 上以 Python 3.10 至 3.14 共 5 个版本组成矩阵运行(其中 3.14 不重复执行 lint 检查),此外还有汇总所有任务结果的 check 任务,以及针对 PR 的 Cloudflare 文档预览任务。

以下三类失败是常见的:

Check Job Failed

Failing PR commit status

该任务失败意味着存在代码格式问题或类型注解问题。查看任务输出定位原因,或在本地 shell 中执行:

$ scripts/check

如果格式问题比较琐碎,可以先运行 scripts/lint 尝试自动格式化,若该任务随后通过,就把格式化结果一起提交。

Docs Job Failed

该任务失败意味着文档构建失败,常见原因包括 Markdown 语法不合法,或 mkdocs.yml 中的配置缺失、引用错误。修复后需确认本地 scripts/docs 能正常启动、页面可访问。

Python 3.X Job Failed

Failing GitHub action test job

该任务失败意味着单元测试未通过,或存在未被测试覆盖的代码路径。区分两种情况:

  • 测试确实失败:覆盖报告中会出现类似 === 1 failed, 435 passed, 1 skipped, 1 xfailed in 11.09s === 的摘要,按上面的 pytest 透传方式(如 scripts/test tests/test_xxx.py)在本地复现并修复;
  • 测试通过但覆盖率不足:覆盖报告会显示 FAIL Required test coverage of 100% not reached. Total coverage: 99.00%。Starlette 对测试覆盖率的要求是 100%(CI 中通过 "Enforce coverage" 步骤强制检查,见 .github/workflows/main.yml),此时需要为新增代码补齐对应的测试用例,测试文件位于 tests/ 目录,与 starlette/ 包内模块一一对应。

发布新版本(面向维护者)

发布流程面向 Starlette 维护者,普通贡献者了解它有助于理解版本号与 changelog 的组织方式。

第一步:发布前的 PR

在发布新版本前,需要创建一个包含以下两部分的 PR:

  • 更新 changelog(docs/release-notes.md):
    • 遵循 keepachangelog 格式;
    • 对照 main 分支与最近一次 release tag 之间的提交,列出对用户有影响的条目;
    • 必须写入:新增(added)、变更(changed)、废弃(deprecated)或移除(removed)的功能,以及 Bug 修复;
    • 不应写入:文档改动、测试改动、工具链改动;
    • 按影响程度从高到低排序,保持简洁、切中要点。
  • 版本号提升:修改 starlette/init.py 中的版本号。这也是项目唯一维护版本号的地方——pyproject.toml 中 [tool.hatch.version] 直接从该文件读取版本。

版本一致性由 scripts/sync-version 自动校验:它用语义化版本正则分别从 docs/release-notes.md 与 starlette/__init__.py 提取版本号并比对,不一致即报错退出。由于 scripts/check 的第一步就是运行 sync-version,任何版本不一致都会在 CI 的 check 任务中暴露。

第二步:创建 Release

发布 PR 合并后,在 GitHub 上创建新 release:

  • Tag 版本:形如 0.13.3;
  • Release 标题:Version 0.13.3;
  • 描述:直接复制 changelog 中对应版本的内容。

Release 创建完成后,会通过发布工作流(见 .github/workflows/publish.yml)自动上传到 PyPI,无需手动操作。

附:开发脚本速查表

脚本 作用 是否修改文件
scripts/install 按 uv.lock 锁定版本安装依赖(uv sync --frozen) 否
scripts/test 非 CI 下先跑 check,再以 coverage 包裹运行 pytest,最后检查覆盖率;参数透传 pytest 否
scripts/lint ruff 自动格式化 + 自动修复 lint 问题(范围 starlette tests) 是
scripts/check 版本一致性校验 + 格式检查 + mypy 严格类型检查 + ruff 静态检查(范围含 benchmarks) 否
scripts/docs 通过 zensical serve 启动本地文档站点 否

完整的脚本清单及设计理念可参考 scripts/README.md,其风格借鉴了 GitHub 的 "Scripts to Rule Them All" 实践——用少量统一入口命令覆盖安装、测试、检查、文档全流程。掌握这套工作流后,从提交一个 Bug 讨论到合入 PR、再到发布新版本,Starlette 的每一个协作环节都有章可循。

登录后查看全文
starlette