如何向 Flask 贡献代码¶
谢谢你打算向 Flask 贡献代码!
问题支持¶
请不要使用 issue tracker 提问。issue tracker 是一个用来报告 Flask 本身的 bug 以及提出新特性请求的工具。对于使用 Flask 时遇到的问题,或是关于你自己代码的问题,请使用下面的资源获取帮助:
The
#questions
channel on our Discord chat: https://discord.gg/pallets如果是长期的讨论或是比较大的问题,可以发到邮件列表 flask@python.org。
在 Stack Overflow 上提问。先使用
site:stackoverflow.com flask {搜索关键词,异常信息等}
在 Google 上搜索。Ask on our GitHub Discussions.
报告 issue¶
在帖子里包含下列信息:
描述期待发生的情况。
如果可能的话,提供一个 最小的可复现的示例 来帮助我们识别 issue。这也会帮助我们确认问题是否出自你自己的代码。
描述实际发生的情况。如果有异常发生,给出完整的错误堆栈信息。
列出 Python 和 Flask 的版本。如果可能的话,检查这个 issue 是不是已经在最新发布的版本中或最新的代码仓库中修复。
提交补丁¶
如果你提交的补丁没有对应的开启的 issue,建议在开始工作前创建一个 issue 进行讨论。你可以着手处理任何没有链接某个开启的 PR 或分配维护者的 issue(这些信息可以在边栏看到)。不需要问是否能处理你感兴趣的 issue,尽管动手去做。
在补丁里包含下列内容:
使用 Black 格式化代码。如果安装了 pre-commit 并使用下面的操作步骤,那么它和其他工具会自动运行。
如果你的补丁增加或改变了某些代码,记得添加对应的测试。确保在没有你的补丁时测试不会通过。
更新任何相关的文档页面和文档字符串。文档页面和文档字符串的行长度应该控制在 72 个字符以内。
在
CHANGES.rst
中添加一个条目。使用和其他条目相同的行文风格。同时在相关的文档字符串使用.. versionchanged::
标签添加行内变更日志。
首次设置¶
下载并安装 最新版本的 git。
-
$ git config --global user.name 'your name' $ git config --global user.email 'your email'
确保你有一个 GitHub 账号。
点击 Fork 按钮把 Flask 复刻(Fork)到你的 GitHub 仓库。
把仓库 克隆 到本地。
$ git clone https://github.com/pallets/flask $ cd flask
把你的复刻仓库作为推送工作代码的远程仓库。使用你的用户名替代
{username}
。这会把远程仓库命名为“fork”,默认的 Pallets 远程仓库为“origin”。$ git remote add fork https://github.com/{username}/flask
创建一个虚拟环境。
$ python3 -m venv env $ . env/bin/activate
> py -3 -m venv env > env\Scripts\activate
更新 pip 和 setuptools。
$ python -m pip install --upgrade pip setuptools
安装开发依赖,然后以编辑模式安装 Flask。
$ pip install -r requirements/dev.txt && pip install -e .
安装 pre-commit 钩子。
$ pre-commit install
开始写代码¶
创建一个分支来标识你想要处理的 issue。如果你在修复一个 bug 或是文档错误,使用最新的“.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
使用你最喜欢的编辑器做出改动,大胆提交代码。
包含覆盖所有变动代码的测试。确保测试在没有你的补丁时会失败。参考下面的说明运行测试。
把你的提交推送到在 GitHub 上的派生仓库并 创建一个拉取请求(pull request)。在拉取请求中使用
fixes #123
链接到关联的 issue。$ git push --set-upstream fork your-branch-name
运行测试¶
使用 pytest 运行基本测试套件。
$ pytest
这会为当前环境运行测试,这通常就足够了。在提交拉取请求时,CI 会运行完整的测试套件。如果你不想等待的话可以使用 tox 运行完整的测试套件。
$ tox
运行测试覆盖率检查¶
生成一份包含测试未覆盖行数的报告,可以指明从哪里开始增加测试。通过 coverage
执行 pytest
来生成报告。
$ pip install coverage
$ coverage run -m pytest
$ coverage html
使用浏览器打开 htmlcov/index.html
浏览报告。
更多内容请参阅 coverage 文档。