如何向 Flask 贡献代码

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

问题支持

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

报告 issue

在帖子里包含下列信息:

  • 描述期待发生的情况。

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

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

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

提交补丁

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

在补丁里包含下列内容:

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

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

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

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

首次设置

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

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

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

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

  • 把仓库 克隆 到本地。

    $ git clone https://github.com/pallets/flask
    $ cd flask
    
  • 把你的复刻仓库作为推送工作代码的远程仓库。使用你的用户名替代 {username}。这会把远程仓库命名为“fork”,默认的 Pallets 远程仓库为“origin”。

    $ git remote add fork https://github.com/{username}/flask
    
  • 创建一个虚拟环境。

    $ python3 -m venv env
    $ . env/bin/activate
    
  • 更新 pip 和 setuptools。

    $ python -m pip install --upgrade pip setuptools
    
  • 安装开发依赖,然后以编辑模式安装 Flask。

    $ pip install -r requirements/dev.txt && pip install -e .
    
  • 安装 pre-commit 钩子。

    $ pre-commit install
    

开始写代码

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

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

运行测试

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

$ pytest

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

$ tox

运行测试覆盖率检查

生成一份包含测试未覆盖行数的报告,可以指明从哪里开始增加测试。通过 coverage 执行 pytest 来生成报告。

$ pip install coverage
$ coverage run -m pytest
$ coverage html

使用浏览器打开 htmlcov/index.html 浏览报告。

更多内容请参阅 coverage 文档

构建文档

docs 目录使用 Sphinx 构建文档。

$ cd docs
$ make html

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

更多内容请参阅 Sphinx 文档