如何为Flask做出贡献

感谢你考虑为 Flask 做出贡献!

支持问题

请不要为此使用问题跟踪程序。请使用以下资源之一解答有关你自己代码的问题:

  • 在 FreeNode 上的 IRC #pocoo 频道。
  • 更普通的问题请使用 FreeNode 上的 IRC #python 频道。
  • 邮件列表flask@python.org,用于长期讨论或更大问题。
  • 在 Stack Overflow 上提问。首先使用以下方法在 Google 上搜索: site:stackoverflow.com flask {search term, exception message, etc.}

报告问题

  • 描述你期望发生的事情。
  • 如果可能,提供一个最小的、完整的和可验证的示例以帮助我们找到问题。 这也有助于鉴别问题是否也你自己的代码有关。
  • 描述实际发生的事情。如果出现异常,请包含完整的回溯。
  • 列出你的 Python 、Flask 和 Werkzeug 版本。如果可能,检查是否这个问题已 在存储库中修复。

提交补丁

  • 如果补丁是用于解决错误的,那么应当包含一个测试,并明确说明错误发生于何种情况之下。确保如果没有补丁,测试就会失败。
  • 尝试遵循 PEP8,但是如果代码行长度限制使用代码更丑陋的话,则可以忽略这条规则。

首次设置

  • 下载并安装最新版的 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]"
    

开始写码

  • 创建一个分支以标识你要处理的问题(例如 2287-dry-test-suite
  • 使用您最喜欢的编辑器修改代码, 随时提交 。
  • 尝试遵循 PEP8,但是如果代码行长度限制使用代码更丑陋的话,则可以忽略这条规则。
  • 应当包含覆盖你所做的全部修改的测试。确保没有补丁则测试失败。 运行测试 。
  • 将你的提交推送到 GitHub 并 创建一个 pull request 。
  • 庆贺成功

运行测试

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

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 的内容。

制作目标

Flask 提供一个 Makefile,包含各种捷径。它们可以保证安装好所有依赖。

  • make test runs the basic test suite with pytest
  • make cov runs the basic test suite with coverage
  • make test-all runs the full test suite with tox
  • make docs 构建HTML文档

警告:零填充文件模式

此存储库包含几个零填充文件模式,当将此存储库推送到GitHub以外的Git主机时,这些模式可能会导致问题。修复此问题会破坏提交历史记录,因此我们建议忽略这些警告。如果推送失败,并且您使用的是像gitlab这样的自托管git服务,则可以在管理面板中关闭存储库检查。

这些文件在克隆时也会导致问题。如果你在 git 配置文件中有以下设置:

[fetch]
fsckobjects = true

或:

[receive]
fsckObjects = true

在Git配置文件中,克隆此存储库将失败。唯一的解决方案是在克隆时将上述两个设置都设置为false,然后在克隆完成后恢复。