后端Web框架【免费下载链接】starletteThe little ASGI framework that shines. 项目地址https://gitcode.com/gh_mirrors/st/starlette点击查看免费下载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/installscripts/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/testscripts/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可以拆解为三步非 CI 环境下先跑scripts/check本地执行时先做同步版本、格式、类型、lint 全量检查确保提交前代码达标在 GitHub Actions 中GITHUB_ACTIONS环境变量非空则跳过因为 CI 已单独执行检查任务避免重复耗时uv run coverage run -m pytest用 coverage 包裹 pytest 运行即测试的同时记录分支覆盖率[tool.coverage.run]中配置了branch true非 CI 环境下再跑scripts/coverage检查覆盖率是否达标。pytest 本身的配置也在 pyproject.toml 中addopts启用了-rXs显示 skip/xfail 摘要、--strict-config、--strict-markersxfail_strict true并把未经过滤的 warning 直接升级为异常保证测试行为严格可控。代码格式化与静态检查scripts/lint 与 scripts/checkscripts/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四步分别对应sync-version校验版本号一致性见下文发布新版本ruff format --check --diff检查格式是否合规并输出差异但不修改文件mypy类型检查pyproject.toml 中strict true采用最严格的类型约束ruff check静态 lint 检查行宽限制为 120pyproject.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.ymlmkdocs.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该任务失败意味着存在代码格式问题或类型注解问题。查看任务输出定位原因或在本地 shell 中执行$ scripts/check如果格式问题比较琐碎可以先运行scripts/lint尝试自动格式化若该任务随后通过就把格式化结果一起提交。Docs Job Failed该任务失败意味着文档构建失败常见原因包括 Markdown 语法不合法或 mkdocs.yml 中的配置缺失、引用错误。修复后需确认本地scripts/docs能正常启动、页面可访问。Python 3.X Job Failed该任务失败意味着单元测试未通过或存在未被测试覆盖的代码路径。区分两种情况测试确实失败覆盖报告中会出现类似 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更新 changelogdocs/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 上创建新 releaseTag 版本形如0.13.3Release 标题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/lintruff 自动格式化 自动修复 lint 问题范围starlette tests是scripts/check版本一致性校验 格式检查 mypy 严格类型检查 ruff 静态检查范围含benchmarks否scripts/docs通过zensical serve启动本地文档站点否完整的脚本清单及设计理念可参考 scripts/README.md其风格借鉴了 GitHub 的 Scripts to Rule Them All 实践——用少量统一入口命令覆盖安装、测试、检查、文档全流程。掌握这套工作流后从提交一个 Bug 讨论到合入 PR、再到发布新版本Starlette 的每一个协作环节都有章可循。赞分享后端Web框架【免费下载链接】starletteThe little ASGI framework that shines. 项目地址https://gitcode.com/gh_mirrors/st/starlette点击查看免费下载相关推荐TanStack Table 贡献指南从提 issue 到合并 PR 的完整开发工作流TanStack Table 贡献指南从提 issue 到合并 PR 的完整开发工作流 导读 TanStack Table 是一个覆盖 React、Vue、S前端UI组件jsdiff开发贡献指南从Issue提交到PR合并的完整流程jsdiff开发贡献指南从Issue提交到PR合并的完整流程 项目概述 jsdiff是一个JavaScript文本差异比较库A javascript tex开发者工具版本控制gensim 开发者贡献指南从提交 Issue 到合并 Pull Request 的完整工作流gensim 开发者贡献指南从提交 Issue 到合并 Pull Request 的完整工作流 本篇指南以仓库根目录的 CONTRIBUTING.md htt人工智能NLP机器学习深度学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
