如何为 Flask 做贡献

感谢您考虑为 Flask 做贡献!

支持问题

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

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

  • Stack Overflow 上提问。先使用以下内容通过 Google 搜索:site:stackoverflow.com flask {search term, exception message, etc.}

  • 对于长期讨论或较大的问题,请在我们的 GitHub 讨论 中提问。

报告问题

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

  • 描述您期望发生的情况。

  • 如果可能,请包含一个 最小可复现示例 以帮助我们识别问题。这还有助于检查问题是否出在您自己的代码中。

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

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

提交补丁

如果您要提交的内容没有公开的问题,请在开始处理 PR 之前优先打开一个问题进行讨论。您可以处理任何没有关联的公开 PR 或没有分配维护者的问题。这些问题显示在侧边栏中。无需询问您是否可以处理您感兴趣的问题。

在您的补丁中包含以下内容

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

  • 如果您的补丁添加或更改了代码,请包含测试。确保在没有补丁的情况下测试会失败。

  • 更新所有相关的文档页面和文档字符串。文档页面和文档字符串应以 72 个字符为单位换行。

  • CHANGES.rst 中添加一个条目。使用与其他条目相同的样式。还应在相关文档字符串中包含 .. versionchanged:: 内联变更日志。

首次使用 GitHub Codespaces 进行设置

GitHub Codespaces 创建了一个已为项目设置好的开发环境。默认情况下,它在 Visual Studio Code for the Web 中打开,但可以在 GitHub 个人资料设置中将其更改为在本地计算机上使用 Visual Studio Code 或 JetBrains PyCharm。

  • 确保您拥有一个 GitHub 帐户

  • 在项目的存储库页面中,单击绿色“代码”按钮,然后单击“在主分支上创建 Codespace”。

  • Codespace 将被设置,然后 Visual Studio Code 将打开。但是,您需要稍等片刻,以便安装 Python 扩展。当底部的终端显示虚拟环境已激活时,您将知道它已准备就绪。

  • 签出分支并 开始编码

在本地环境中首次设置

  • 确保您拥有一个 GitHub 帐户

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

  • 使用您的 用户名电子邮件 配置 git。

    $ git config --global user.name 'your name'
    $ git config --global user.email 'your email'
    
  • 通过单击 Fork 按钮将 Flask 分叉到您的 GitHub 帐户。

  • 克隆 您本地的分叉,将以下命令中的 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
    

开始编码

  • 创建一个分支来标识您想要处理的问题。如果您提交的是错误或文档修复,请从最新的“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
    
  • 使用您最喜欢的编辑器,进行更改,随时提交

    • 如果您在代码空间中,系统会提示您创建分支,这是您第一次提交。输入Y继续。

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

  • 将您的提交推送到 GitHub 上的分支,并创建拉取请求。在拉取请求描述中使用fixes #123链接到正在解决的问题。

    $ 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 的更多信息。

构建文档

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

$ cd docs
$ make html

在浏览器中打开 _build/html/index.html 以查看文档。

阅读有关 Sphinx 的更多信息。