如何向 Flask 贡献代码

谢谢你打算向 Flask 贡献代码！

问题支持

请不要使用 issue tracker 提问。issue tracker 是一个用来报告 Flask 本身的 bug 以及提出新特性请求的工具。对于使用 Flask 时遇到的问题，或是关于你自己代码的问题，请使用下面的资源获取帮助：

  • 我们的 Discord 聊天组的 #questions 频道：https://discord.gg/pallets

  • 在 Stack Overflow 上提问。先使用 site:stackoverflow.com flask {搜索关键词，异常信息等} 在 Google 上搜索。

  • 如果是长期的讨论或是比较大的问题，可以到 GitHub Discussions 上提问。

报告 issue

在帖子里包含下列信息：

  • 描述期待发生的情况。

  • 如果可能的话，提供一个 最小的可复现的示例 来帮助我们识别 issue。这也会帮助我们确认问题是否出自你自己的代码。

  • 描述实际发生的情况。如果有异常发生，给出完整的错误堆栈信息。

  • 列出 Python 和 Flask 的版本。如果可能的话，检查这个 issue 是不是已经在最新发布的版本中或最新的代码仓库中修复。

提交补丁

如果你提交的补丁没有对应的开启的 issue，建议在开始工作前创建一个 issue 进行讨论。你可以着手处理任何没有链接某个开启的 PR 或分配维护者的 issue（这些信息可以在边栏看到）。不需要问是否能处理你感兴趣的 issue，尽管动手去做。

在补丁里包含下列内容：

  • 使用 Black 格式化代码。如果安装了 pre-commit 并使用下面的操作步骤，那么它和其他工具会自动运行。

  • 如果你的补丁增加或改变了某些代码，记得添加对应的测试。确保在没有你的补丁时测试不会通过。

  • 更新任何相关的文档页面和文档字符串。文档页面和文档字符串的行长度应该控制在 72 个字符以内。

  • 在 CHANGES.rst 中添加一个条目。使用和其他条目相同的行文风格。同时在相关的文档字符串使用 .. versionchanged:: 标签添加行内变更日志。

使用 GitHub Codespaces 的首次设置

GitHub Codespaces 会创建一个已为项目配置好的开发环境。默认情况下，它会在 Web 版的 Visual Studio Code 中打开， 但你也可以在 GitHub 个人设置中修改为在你的本地计算机上使用 Visual Studio Code 或 JetBrains PyCharm。

  • 确保你有一个 GitHub 账号。

  • 在项目的仓库页面中，点击绿色的 “Code” 按钮，然后选择 “Create codespace on main”。

  • 系统会开始设置 codespace，之后 Visual Studio Code 会自动打开。 不过，你需要再稍等片刻，以便 Python 扩展安装完成。 当底部的终端显示虚拟环境（virtualenv）已被激活时，说明一切准备就绪。

  • 签出一个分支然后 开始编码。

在本地环境中进行首次设置

  • 确保你有一个 GitHub 账号。

  • 下载并安装 最新版本的 git。

  • 使用你的 用户名 和 Email 配置 git。

    $ git config --global user.name 'your name'
$ git config --global user.email 'your email'

  • 点击 Fork 按钮把 Flask 复刻（Fork）到你的 GitHub 仓库。

  • 在本地 克隆 你的复刻（fork），使用你的真实用户名替代下面命令中的 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 钩子。

    $ pre-commit install --install-hooks

开始写代码

  • 创建一个分支来标识你想要处理的 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 上的派生仓库（your fork）并 create a pull request`_（创建一个拉取请求，即 pull request）。在拉取请求中使用 ``fixes #123` 链接到关联的 issue。

    $ 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 文档。

构建文档

在 docs 目录使用 Sphinx 构建文档。

$ cd docs
$ make html

使用浏览器打开 _build/html/index.html 预览文档。

更多内容请参阅 Sphinx 文档。