为该项目做出贡献

清单

  1. 所有潜在贡献者必须阅读贡献者行为准则并遵守该准则

  2. 在GitHub或GitLab上分叉存储库

  3. 创建一个新分支，例如，git checkout -b bug/12345

  4. 修复错误并添加测试（如果适用[1]，请参阅如何添加测试）

  5. 运行测试（请参阅以下如何运行测试）

  6. 为您的更改添加文档（必要时）

  7. 构建文档以检查错误和格式（请参阅以下如何构建文档）

  8. 将您自己添加到AUTHORS.rst（除非您已在其中）

  9. 提交它。在您的提交消息中遵循这些规则

    • 将主题行保持在 50 个字符以内

    • 使用命令动词开始提交

    • 在主题和消息之间使用空行

    • 在提交的留言部分详细描述原因

    • 将消息的行换行到 72 个字符

    • 添加适当的“Closes #12345”语法以自动关闭它修复的问题（如果它关闭了一个问题）

    • 请参阅以下示例提交消息

  10. 将其推送到您的分叉

  11. 创建请求，让我们合并您的贡献

在此最后一步之后，我们可能会以审查评论的形式留下反馈。在处理这些评论时，您可以遵循两种策略

  • 修改/将您的更改重新基于到现有提交中

  • 创建一个带有不同消息的新提交[2]，描述该提交中的更改，并将其推送到您的分支

该项目不会对您应该偏好的方法发表意见。我们只要求您了解以下内容

  • GitHub 和 GitLab 都不会通知我们您已推送新更改。建议您友好地 ping 一下

  • 如果您继续使用您创建请求时的同一分支，GitHub 和 GitLab 都会在网站上更新请求。您不需要为新更改创建新请求。

贡献者行为准则

作为该项目的贡献者和维护者，为了培养一个开放和欢迎的社区，我们承诺尊重所有通过报告问题、发布功能请求、更新文档、提交请求或补丁以及其他活动做出贡献的人员。

我们致力于让参与此项目成为对每个人来说没有骚扰的体验，无论其经验水平、性别、性别认同和表达、性取向、残疾、个人外表、体型、种族、民族、年龄、宗教或国籍如何。

参与者不可接受的行为示例包括

  • 使用性暗示的语言或图像

  • 人身攻击

  • 捣乱或侮辱/贬低评论

  • 公开或私下骚扰

  • 在未经明确许可的情况下发布他人的私人信息，例如物理或电子地址

  • 其他不道德或不专业的行为

项目维护者有权且有责任删除、编辑或拒绝与本行为准则不一致的评论、提交、代码、维基编辑、问题和其他贡献，或暂时或永久禁止任何被认为不当、威胁、冒犯或有害的其他行为的贡献者。

通过采纳本行为准则，项目维护者承诺公平和一致地将这些原则应用于管理此项目的各个方面。不遵守或不执行行为准则的项目维护者可能会被永久移除出项目团队。

本行为准则适用于项目空间和公共空间，当个人代表项目或其社区时。

可以通过联系项目维护者 graffatcolmingov@gmail.com 报告辱骂、骚扰或其他不可接受的行为。所有投诉都将得到审查和调查，并将根据情况做出必要和适当的回应。维护者有义务对事件报告人保密。

本行为准则改编自 贡献者契约，版本 1.3.0，可在 https://www.contributor-covenant.org/version/1/3/0/ 获得

如何添加测试

我们使用 pytest 运行测试并简化我们编写测试的方式。如果您正在修复现有模块中的错误，请找到该模块或功能的测试并添加到其中。大多数测试位于 tests 目录中。如果您正在新子模块中添加新功能，请创建一个新的测试代码模块。例如，如果您要添加名为 foo 的子模块，那么您将创建 tests/test_foo.py，其中将包含 foo 子模块的测试。

如何运行测试

使用 tox 运行此项目中的测试。在运行测试之前，请确保您已使用系统包管理器（例如 apt、yum 等）或您首选的 python 安装程序（例如 pip）安装了 tox。

然后至少在 Python 2.7 和 Python 3.x 上运行测试，例如

$ tox -e py27,py34

最后运行一个或两个 flake8 样式强制程序，例如

$ tox -e py27-flake8
# or
$ tox -e py34-flake8

如果您同时运行这两个程序，则可以捕获 Python 2 或 Python 3 中可能发生的语法错误（具体取决于您对两种语言的公共子集的熟悉程度）。

Tox 将为您管理虚拟环境和依赖项，因此它将是您为该项目做出贡献所需的唯一依赖项。

如何构建文档

要构建文档，你需要确保已安装 tox，然后可以运行

$ tox -e docs

这会将文档构建到 docs/_build/html 中。如果你然后运行

$ python2.7 -m SimpleHTTPServer
# or
$ python3.4 -m http.server

从该目录，你可以在 https://127.0.0.1:8000/ 本地查看文档。

示例提交消息

Allow users to use the frob when uploading data

When uploading data with FooBar, users may need to use the frob method
to ensure that pieces of data are not munged.

Closes #1234567

发布新版本

  1. 准备发布拉取请求

    • 在 requests_toolbelt/__init__.py 中，提高版本号

    • 在 HISTORY.rst 中，将值得注意的更改包含在相关章节下

    • 使用上述更改打开一个拉取请求，并进行任何必需的更改以获得批准

  2. 在 GitHub 中“合并并压扁”拉取请求，这会给你一个发布提交

  3. 使用该提交标记发布

    • 创建标记： git tag -s -a $VERSION -m "Release v$VERSION"

    • 将其推送到主仓库（不是你的分支）： git push <remote> --tags

  4. 使用 tox -e release 在 PyPI 上上传它

  5. [可选] 在相关位置（社交媒体、GitHub 问题……）宣布它

脚注