贡献;促成;投稿;捐献 (这个词有多种含义,具体翻译需根据上下文来确定)
感谢您对为 Starlette 做出贡献感兴趣。您可以通过多种方式为该项目做出贡献:
报告错误或其他问题
发现了 Starlette 应该支持的东西?偶然遇到了一些意外行为?
贡献通常应以讨论开始。可能的错误可以作为“潜在问题”讨论提出,功能请求可以作为“想法”讨论提出。然后,我们可以确定该讨论是否需要升级为“问题”,或者我们是否会考虑拉取请求。
尽量描述得更详细些,在提交错误报告的情况下,尽可能提供更多信息,例如:
- 操作系统平台
- Python 版本
- 已安装的依赖项和版本(
python -m pip freeze
) - 代码片段
- 错误跟踪回溯
您应该始终尝试将任何示例简化为能够说明问题的最简单的可能情况。
开发;发展
要开始开发 Starlette,在 GitHub 上为 Starlette 仓库创建一个分支。
然后使用以下命令克隆您的分支,将 YOUR-USERNAME
替换为您的 GitHub 用户名:
$ git clone https://github.com/YOUR-USERNAME/starlette
您现在可以使用以下命令安装项目及其依赖项:
$ cd starlette
$ scripts/install
测试与代码检查
我们使用自定义的 shell 脚本以实现测试、代码检查和文档构建工作流程的自动化。
要运行这些测试,请使用:
$ scripts/test
任何其他参数将传递给 pytest
。有关更多信息,请参阅 pytest 文档。
例如,运行单个测试脚本:
$ scripts/test tests/test_application.py
要运行代码自动格式化:
$ scripts/lint
最后,要单独运行代码检查(它们也作为 scripts/test
的一部分运行),请运行:
$ scripts/check
记录;编制文件
文档页面位于 docs/
文件夹下。
要在本地运行文档站点(对预览更改很有用),请使用:
$ scripts/docs
解决构建/持续集成失败问题
一旦您提交了拉取请求,测试套件将自动运行,结果将显示在 GitHub 上。如果测试套件失败,您需要点击“详细信息”链接,并尝试找出测试套件失败的原因。
以下是测试套件可能失败的一些常见方式:
检查作业失败
此工作失败意味着要么存在代码格式问题,要么存在类型注释问题。您可以查看工作输出以弄清楚其失败的原因,或者在 shell 中运行:
$ scripts/check
运行 $ scripts/lint
以尝试自动格式化代码可能是值得的,如果该操作成功,则提交更改。
文档作业失败
此工作失败意味着文档构建失败。这可能由于多种原因发生,例如无效的 Markdown 或 mkdocs.yml
内缺少配置。
Python 3.X 作业失败
此工作失败意味着单元测试失败或并非所有代码路径都被单元测试覆盖。
如果测试失败,您将在覆盖率报告下看到此消息:
=== 1 failed, 435 passed, 1 skipped, 1 xfailed in 11.09s ===
如果测试成功,但覆盖率未达到我们当前的阈值,您将在覆盖率报告下看到此消息:
FAIL Required test coverage of 100% not reached. Total coverage: 99.00%
发布;释放;发行
此部分面向 Starlette 维护者。
在发布新版本之前,创建一个包含以下内容的拉取请求:
- 对变更日志的一次更新:
- 我们遵循 keepachangelog 的格式。
- 将
master
与最新版本的标签进行比较,并列出所有我们用户感兴趣的条目:- 必须在变更日志中记录的内容:添加、更改、弃用或删除的功能以及错误修复。
- 不应记录在变更日志中的内容:文档、测试或工具方面的变更。
- 尝试按照影响/重要性的降序对条目进行排序。
- 保持简洁且切中要点。🎯
- 一个版本提升:见
__version__.py
。
例如,见 #1600 。
一旦发布公关(PR)被合并,创建一个新的发布,包括:
- 标签版本如
0.13.3
。 - 发布标题
Version 0.13.3
- 描述从变更日志中复制。
一旦创建,此版本将自动上传到 PyPI 。
如果 PyPI 任务出现问题,可以使用 scripts/publish
脚本发布版本。