如何为 Flask 做出贡献

首次设置¶

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

• 配置使用 git 的 username 和 email:

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

• 确保你有一个 GitHub 账号.

• 点击 Fork 按钮将 Flask fork 到你的 GitHub 账户。

• 把你的 GitHub fork Clone 到本地:

  git clone https://github.com/{username}/flask
  cd flask
  

• 添加一个主存储库作为远程库，稍后更新:

  git remote add pallets https://github.com/pallets/flask
  git fetch pallets
  

• 创建一个 virtualenv:

  python3 -m venv env
  . env/bin/activate
  # or "env\Scripts\activate" on Windows
  

• 在带有开发依赖的编辑模式下安装 Flask:

  pip install -e ".[dev]"
  

• 安装 pre-commit 钩子:

  pre-commit install --install-hooks
  

开始写代码¶

• 创建一个分支来鉴别你想要处理的问题。如果要提交一个缺陷或者文档修正，请从 最后的“ .x ”分支来创建分支:

  git checkout -b your-branch-name origin/1.0.x
  

  如果要提交一个功能增加或者更改，请从“ master ”分支来创建分支:

  git checkout -b your-branch-name origin/master
  

• 使用你最喜欢的编辑器，修改代码， 随时提交 。

• 应当包含覆盖你所做的全部修改的测试。确保没有补丁则测试失败。 运行测试 。

• 将你的提交推送到 GitHub 并 创建一个 pull request

  git push --set-upstream origin your-branch-name
  

• 庆祝成功 ????

运行测试¶

用以下命令运行基础测试:

pytest

这只在当前环境下运行测试。这是否相关取决于你在处理 Flask 的哪个部分。 当你提交 pull request 时， Travis-CI 会运行全部测试。

完整的测试套件运行时间会很长，因为它会在多种 Python 及其依赖的环境下运行。 在所有环境下运行测试需要有 Python 2.7 、 3.4 、 3.5 、 3.6 和 PyPy 2.7 。 然后运行:

tox

运行测试覆盖¶

生成一个哪些代码未被测试覆盖的报告可以指明从哪里开始贡献。使用 coverage 运行 pytest 并在终端生成一个报告和一份交互 HTML 文档:

coverage run -m pytest
coverage report
coverage html
# then open htmlcov/index.html

请阅读更多关于 coverage 的文档。

用 tox 运行完整测试套件会组合所有运行测试的覆盖报告。

构建文档¶

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

cd docs
make html

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

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