如何为Flask做出贡献¶
感谢你考虑为 Flask 做出贡献!
支持问题¶
请不要使用问题跟踪器进行此操作。问题跟踪器是一种工具,用于解决Flask本身中的错误和功能请求。使用以下资源之一解决有关使用FlaskTM或您自己的代码问题的问题:
这个
#questions
我们不和谐聊天的频道:https://discord.gg/pallets问吧 Stack Overflow 。首先使用谷歌搜索:
site:stackoverflow.com flask {search term, exception message, etc.}
请在我们的 GitHub Discussions 用于长期讨论或更大的问题。
报告问题¶
在您的帖子中包含以下信息:
描述你期望发生的事情。
如果可能,包括 minimal reproducible example 帮助我们找出问题所在。这也有助于检查问题是否与您自己的代码无关。
描述实际发生的事情。如果出现异常,请包含完整的回溯。
列出您的Python和Flask版。如果可能,请检查最新版本或存储库中的最新代码是否已修复此问题。
提交补丁¶
如果您想要提交的内容没有公开的问题,最好在处理PR之前打开一个进行讨论。您可以处理任何没有公开PR链接或没有分配给它的维护者的问题。这些显示在侧边栏中。不需要问你是否能解决你感兴趣的问题。
在修补程序中包括以下内容:
使用 Black 格式化代码。如果安装,此工具和其他工具将自动运行 pre-commit 使用以下说明。
如果修补程序添加或更改代码,则包括测试。确保测试在没有补丁的情况下失败。
更新任何相关的文档页面和docstring。Docs页面和docstring应该用72个字符包装。
在中添加条目
CHANGES.rst
. 使用与其他条目相同的样式。还包括.. versionchanged::
相关docstring中的内联变更日志。
使用GitHub代码空间进行首次设置¶
GitHub Codespaces 创建已为项目设置的开发环境。默认情况下,它在用于Web的Visual Studio代码中打开,但可以在GitHub配置文件设置中进行更改,以在本地计算机上使用Visual Studio代码或JetBrains PYCharm。
确保你有一个 GitHub 账号.
在项目的存储库页面中,单击绿色的“Code”按钮,然后单击“Create CodeSpace on Main”。
将设置CodeSpace,然后打开Visual Studio代码。但是,您需要等待更长时间才能安装Python扩展。当底部的终端显示Virtualenv被激活时,您就会知道它已经准备好了。
看看一家分行,然后 start coding 。
在您的本地环境中进行首次设置¶
确保你有一个 GitHub 账号.
下载并安装最新版的 git.
-
$ git config --global user.name 'your name' $ git config --global user.email 'your email'
点击 Fork 按钮将 Flask fork 到你的 GitHub 账户。
Clone 您的叉子在本地,更换
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
开始写码¶
创建一个分支来确定您要处理的问题。如果您正在提交一个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
使用您最喜欢的编辑器修改代码, 随时提交 。
如果您在CodeSpace中,系统将提示您 create a fork 你第一次做出承诺的时候。请输入
Y
才能继续。
包括覆盖您所做的任何代码更改的测试。确保测试在没有补丁的情况下失败。按如下所述运行测试。
把你的承诺推到GitHub上的分叉上,然后 create a pull request 。指向正在解决的问题的链接
fixes #123
在拉取请求描述中。$ git push --set-upstream origin your-branch-name
运行测试¶
使用pytest运行基本测试套件。
$ pytest
这将为当前环境运行测试,这通常就足够了。当您提交请求时,CI将运行完整套件。如果你不想等的话,你可以用tox来运行完整的测试套件。
$ tox
运行测试覆盖率¶
生成没有测试覆盖率的行的报告可以指示从何处开始贡献。跑 pytest
使用 coverage
并生成报告。
如果您使用的是GitHub代码空间, coverage
已安装,因此您可以跳过安装命令。
$ pip install coverage
$ coverage run -m pytest
$ coverage html
正常开放 htmlcov/index.html
在浏览器中浏览报表。
阅读更多有关 coverage .
构建文档¶
在中生成文档 docs
使用Sphinx的目录。
$ cd docs
$ make html
在浏览器中打开 _build/html/index.html 以查看文档。
阅读更多有关 Sphinx .