如何为 Flask 做贡献¶
感谢您考虑为 Flask 做贡献!
支持问题¶
请不要为此使用问题跟踪器。问题跟踪器是一个用于解决 Flask 本身中的错误和功能请求的工具。对于有关使用 Flask 的问题或您自己的代码问题,请使用以下资源之一
我们 Discord 聊天中的
#questions
频道:https://discord.gg/pallets在 Stack Overflow 上提问。先使用以下内容通过 Google 搜索:
site:stackoverflow.com flask {search term, exception message, etc.}
对于长期讨论或较大的问题,请在我们的 GitHub 讨论 中提问。
报告问题¶
在您的帖子中包含以下信息
描述您期望发生的情况。
如果可能,请包含一个 最小可复现示例 以帮助我们识别问题。这还有助于检查问题是否出在您自己的代码中。
描述实际发生的情况。如果出现异常,请包含完整的回溯。
列出您的 Python 和 Flask 版本。如果可能,请检查此问题是否已在最新版本或存储库中的最新代码中修复。
提交补丁¶
如果您要提交的内容没有公开的问题,请在开始处理 PR 之前优先打开一个问题进行讨论。您可以处理任何没有关联的公开 PR 或没有分配维护者的问题。这些问题显示在侧边栏中。无需询问您是否可以处理您感兴趣的问题。
在您的补丁中包含以下内容
使用 Black 格式化您的代码。如果您按照以下说明安装 pre-commit,此工具和其他工具将自动运行。
如果您的补丁添加或更改了代码,请包含测试。确保在没有补丁的情况下测试会失败。
更新所有相关的文档页面和文档字符串。文档页面和文档字符串应以 72 个字符为单位换行。
在
CHANGES.rst
中添加一个条目。使用与其他条目相同的样式。还应在相关文档字符串中包含.. versionchanged::
内联变更日志。
首次使用 GitHub Codespaces 进行设置¶
GitHub Codespaces 创建了一个已为项目设置好的开发环境。默认情况下,它在 Visual Studio Code for the Web 中打开,但可以在 GitHub 个人资料设置中将其更改为在本地计算机上使用 Visual Studio Code 或 JetBrains PyCharm。
在本地环境中首次设置¶
确保您拥有一个 GitHub 帐户。
下载并安装 最新版本的 git。
-
$ git config --global user.name 'your name' $ git config --global user.email 'your email'
通过单击 Fork 按钮将 Flask 分叉到您的 GitHub 帐户。
克隆 您本地的分叉,将以下命令中的
your-username
替换为您的实际用户名。$ git clone https://github.com/your-username/flask $ cd flask
创建一个虚拟环境。使用最新版本的 Python。
Linux/macOS
$ python3 -m venv .venv $ . .venv/bin/activate
Windows
> py -3 -m venv .venv > .venv\Scripts\activate
安装开发依赖项,然后以可编辑模式安装 Flask。
$ python -m pip install -U pip $ pip install -r requirements/dev.txt && pip install -e .
安装预提交钩子。
$ pre-commit install --install-hooks
开始编码¶
创建一个分支来标识您想要处理的问题。如果您提交的是错误或文档修复,请从最新的“x”分支中分支出来。
$ git fetch origin $ git checkout -b your-branch-name origin/2.0.x
如果您提交的是功能添加或更改,请从“main”分支中分支出来。
$ git fetch origin $ git checkout -b your-branch-name origin/main
使用您最喜欢的编辑器,进行更改,随时提交。
如果您在代码空间中,系统会提示您创建分支,这是您第一次提交。输入
Y
继续。
包含涵盖您所做的任何代码更改的测试。确保在没有补丁的情况下测试失败。按如下所述运行测试。
将您的提交推送到 GitHub 上的分支,并创建拉取请求。在拉取请求描述中使用
fixes #123
链接到正在解决的问题。$ git push --set-upstream origin your-branch-name
运行测试¶
使用 pytest 运行基本测试套件。
$ pytest
这会运行当前环境的测试,这通常就足够了。当您提交拉取请求时,CI 将运行完整套件。如果您不想等待,可以使用 tox 运行完整测试套件。
$ tox
运行测试覆盖率¶
生成没有测试覆盖率的行报告可以指示从哪里开始做出贡献。使用coverage
运行pytest
并生成报告。
如果您使用的是 GitHub Codespaces,coverage
已经安装,因此您可以跳过安装命令。
$ pip install coverage
$ coverage run -m pytest
$ coverage html
在浏览器中打开htmlcov/index.html
以浏览报告。
阅读有关 coverage 的更多信息。
构建文档¶
使用 Sphinx 在 docs
目录中构建文档。
$ cd docs
$ make html
在浏览器中打开 _build/html/index.html
以查看文档。
阅读有关 Sphinx 的更多信息。