如何为Flask做出贡献

感谢你考虑为 Flask 做出贡献!

支持问题

请不要使用问题跟踪程序。问题跟踪器是一个工具,用于解决Flask本身的缺陷和特性请求。对于有关使用Flask的问题或与您自己的代码有关的问题,请使用以下资源之一:

  • 这个 #get-help 不和谐聊天频道:https://discord.gg/pallets

  • 邮件列表flask@python.org,用于长期讨论或更大问题。

  • Stack Overflow . 首先使用谷歌搜索: site:stackoverflow.com python flask {{search term, exception message, etc.}}

报告问题

在您的帖子中包含以下信息:

  • 描述你期望发生的事情。

  • 如果可能,包括 minimal reproducible example 帮助我们找出问题所在。这也有助于检查问题是否与您自己的代码无关。

  • 描述实际发生的事情。如果出现异常,请包含完整的回溯。

  • 列出您的Python、Flask和Werkzeug版本。如果可能,请检查此问题是否已在最新版本或存储库中的最新代码中修复。

提交补丁

如果您想要提交的内容没有公开的问题,最好在处理PR之前打开一个进行讨论。您可以处理任何没有公开PR链接或没有分配给它的维护者的问题。这些显示在侧边栏中。不需要问你是否能解决你感兴趣的问题。

在修补程序中包括以下内容:

  • 使用 Black 格式化代码。如果安装,此工具和其他工具将自动运行 pre-commit 使用以下说明。

  • 如果修补程序添加或更改代码,则包括测试。确保测试在没有补丁的情况下失败。

  • 更新任何相关的文档页面和docstring。Docs页面和docstring应该用72个字符包装。

  • 在中添加条目 CHANGES.rst . 使用与其他条目相同的样式。还包括 .. versionchanged:: 相关docstring中的内联变更日志。

首次设置

  • 下载并安装最新版的 git.

  • 使用您的 usernameemail .

    $ git config --global user.name 'your name'
    $ git config --global user.email 'your email'
    
  • 确保你有一个 GitHub 账号.

  • 点击 Fork 按钮将 Flask fork 到你的 GitHub 账户。

  • Clone 本地主存储库。

    $ git clone https://github.com/pallets/flask
    $ cd flask
    
  • 把你的叉子当作遥控器来推动你的工作。替换 {{username}} 使用您的用户名。这将远程托盘命名为“fork”,默认托盘远程托盘为“origin”。

    git remote add fork https://github.com/{username}/flask
    
  • 创建一个virtualenv。

    $ python3 -m venv env
    $ . env/bin/activate
    
    > py -3 -m venv env
    > env\Scripts\activate
    
  • 在具有开发依赖项的可编辑模式下安装Flask。

    $ pip install -e . -r requirements/dev.txt
    
  • 安装预提交挂钩。

    $ pre-commit install
    

开始写码

  • 创建一个分支来确定您要处理的问题。如果您正在提交一个bug或文档修复程序,请从最新的“.x”分支分支分支。

    $ git fetch origin
    $ git checkout -b your-branch-name origin/1.1.x
    

    如果您要提交特性添加或更改,请从“主”分支分支分支。

    $ git fetch origin
    $ git checkout -b your-branch-name origin/master
    
  • 使用您最喜欢的编辑器修改代码, 随时提交 。

  • 包括覆盖您所做的任何代码更改的测试。确保测试在没有补丁的情况下失败。按如下所述运行测试。

  • 把你的承诺推到GitHub上的fork,然后 create a pull request . 与正在解决的问题的链接 fixes #123 在拉请求中。

    $ git push --set-upstream fork your-branch-name
    

运行测试

使用pytest运行基本测试套件。

$ pytest

这将为当前环境运行测试,这通常就足够了。当您提交请求时,CI将运行完整套件。如果你不想等的话,你可以用tox来运行完整的测试套件。

$ tox

运行测试覆盖率

生成没有测试覆盖率的行的报告可以指示从何处开始贡献。跑 pytest 使用 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 .