如何为Flask做出贡献

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

支持问题

请不要使用问题跟踪器进行此操作。问题跟踪器是一种工具,用于解决Flask本身中的错误和功能请求。使用以下资源之一解决有关使用FlaskTM或您自己的代码问题的问题:

报告问题

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

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

  • 如果可能,包括 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.

  • 使用您的 usernameemail .

    $ 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 .