如何为 Flask 做出贡献

感谢您为 Flask 做出贡献！

问答支持

问题跟踪器的用途是记录 Flask 本身相关的问题和功能需求的，因此请不要使用问题跟踪器来提问。如果有关于 Flask 使用方面或者你自己代码的方面的问题，请使用下列途径之一提问：

Discord chat 上的 #questions 频道： https://discord.gg/pallets
邮件列表 flask@python.org 用于长期或者大型问题讨论。
在 Stack Overflow 上提问。提问前请先使用以下方法在 Google 上搜索： site:stackoverflow.com flask {search term, exception message, etc.}
在我们的 GitHub 讨论上提问。

请在报告中包含以下内容：

在提交一个 PR 之前，如果没有相关的开放议题，那么建议打开一个新的相关议题讨论一下。如果你对某个议题感兴趣，而这个议题没有相关联的 PR 也没有指定维护人，那么你就直接上手吧，不需要征得同意。

提交补丁应当做好以下工作：

使用 Black 格式化你的代码。如果按照下面的介绍，安装好了 pre-commit ，那么这个工具及其他的工具都可以自动运行。
如果补丁增加或者改动了代码，那么应当包含测试，并确保如果没有补丁，测试就会失败。
更新所有的相关文档页面和 docstring 。文档页面和 docstring 应当在第 72 个字符处换行。
在 CHANGES.rst 中增加一个条目，条目的样式与其他条目相同。同时，在相关的 docstring 中包含 .. versionchanged:: 行内变更记录。

配置使用 git 的 username 和 email 。

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

把主仓库 Clone 到本地。

$ git clone https://github.com/pallets/flask
$ cd flask

把你的工作作为一个远程分支，用你的用户名替换 {username} ，这样对远程分支进行了命名，缺省的 Pallets 远程分支名为 “origin” 。
```
$ git remote add fork https://github.com/{username}/flask
```

创建一个 virtualenv 。

Linux/macOSWindows

$ python3 -m venv env
$ . env/bin/activate

> py -3 -m venv env
> env\Scripts\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
```

   $ 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 上你的分支中，并创建一个拉取请求。在拉取请求中链接类似 fixes #123 的议题。
```
$ 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 的文档。

使用 Sphinx 构建 docs 文件夹中的文档。

$ cd docs
$ make html

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

请阅读更多关于 Sphinx 的内容。