贡献

这是一个 Jazzband 项目。通过贡献，您同意遵守 Contributor Code of Conduct 并遵循 guidelines 。

布设

叉 django-oauth-toolkit 存储库位于 GitHub 并遵循以下步骤：

• 创建并激活一个虚拟环境

• 在本地克隆您的存储库

议题

您可以在上找到错误、增强和功能请求的列表 issue tracker 。如果你想解决一个问题，拿起一个，然后添加一个评论，说明你正在努力解决这个问题。

代码样式

该项目使用 flake8 对于皮棉来说， black 为了格式化代码， isort 用于设置导入的格式和排序，以及 pre-commit 用于在提交之前检查/修复提交的正确性。

您将需要安装 pre-commit 你自己，然后 pre-commit 将负责安装 flake8 ， black 和 isort 。

克隆存储库后，进入存储库并运行：：

pre-commit install

来安装吊钩。在你下一次承诺的时候， pre-commit 将下载并安装必要的挂钩(一次性任务)。如果提交中的任何内容导致钩子失败，则将放弃该提交。为 black 和 isort ，任何必要的更改都将自动进行，但不会分阶段进行。复查更改，然后重新暂存并再次提交。

vbl.使用 pre-commit 确保在QA中失败的代码一开始就不会提交，并且从长远来看将节省您的时间。您也可以(在很大程度上)不再担心代码样式，尽管您应该始终检查代码是如何处理的 black 已经格式化了它，并考虑是否有更好的方法来组织代码，使其更具可读性。

文档

您可以通过在中编辑文件来编辑文档 docs/ 。该项目使用狮身人面像将 ReStructuredText 到您正在阅读的HTML文档中。

为了将文档构建到HTML中，您可以运行：：

tox -e docs

这将构建文档，并将结果放在 docs/_build/html 。或者，您可以运行：

tox -e livedocs

这将运行 sphinx 在实时重新加载模式下，因此您对 RST 系统将自动检测文件并重建HTML文件。它还将运行一个简单的HTTP服务器，网址为 http://localhost:8000/ 提供HTML文件，并在发生更改时自动重新加载页面。

这使您可以编辑文档，并在浏览器中立即看到所做的更改。

• ReStructuredText primer

译文

您可以使用以下工具提供国际语言翻译 django-admin makemessages 。

例如，要添加Deutsch：：

cd oauth2_provider
django-admin makemessages --locale de

然后编辑 locale/de/LC_MESSAGES/django.po 若要添加翻译，请执行以下操作。

在部署您的应用程序时，不要忘记使用：：编译消息

django-admin compilemessages

迁徙

如果更改任何模型，将需要生成新的迁移。新的贡献者经常错过这一步。您可以使用以下命令检查是否需要新的迁移：

tox -e migrations

如果需要新的迁移，请使用：：

django-admin makemigrations --settings tests.mig_settings

自动迁移经常有难听的名称，如 0004_auto_20200902_2022 。您可以通过添加 -n name 选项：：

django-admin makemigrations --settings tests.mig_settings -n widget

拉请求

请避免从您的 master 和使用 topic branches 相反，您可以添加任意数量的提交，但请将它们放在一个旨在解决单个问题的分支中。然后提交您的拉取请求。要创建主题分支，只需执行以下操作：：

git checkout -b fix-that-issue
Switched to a new branch 'fix-that-issue'

当您准备好提交Pull请求时，首先将主题分支推送到您的GitHub repo：：

git push origin fix-that-issue

现在您可以转到GitHub上的存储库仪表板，并从您的主题分支开始打开一个拉入请求。您可以将拉入请求应用于 master Django-OAuth-TOOLKIT的分支(这应该是GitHub用户界面的默认行为)。

当您开始公关时，您将被要求提供以下内容：

• 确定此PR修复的问题编号(如果有)。当您的公关被接受和合并时，该问题将自动结束。

• 提供更改的高级描述。评审员应该能够在不必阅读提交的情况下告诉您的公关做了什么(S)。

• 确保PR只包含一项更改。尽量保持公关规模小，注意力集中。您可以随时提交其他PR。

• 任何新的或更改的代码都需要添加或更新单元测试。确保您的测试检查正确的错误行为以及正常的预期行为。争取对您贡献的任何新代码进行100%的代码覆盖率！改进单元测试总是一个受欢迎的贡献。如果您的更改减少了覆盖范围，您将收到以下警告 Codecov 。

• 更新文档(在 docs/ )来描述新的或更改的功能。

• 更新 CHANGELOG.md (仅限与用户相关的更改)。我们用 Keep A Changelog 将更改分类为以下内容的格式：

  • Added 以获取新功能。

  • Changed 用于现有功能的更改。

  • Deprecated 用于即将移除的功能。

  • Removed 目前已删除的功能。

  • Fixed 用于任何错误修复。

  • Security 以防出现漏洞。(如有任何保安问题，请向

    JazzBand安全团队 <security@jazzband.co> 。在收到指示之前，不要在跟踪器上提交问题或提交公关。)

• 确保你的名字在 AUTHORS 。我们想向所有的贡献者致敬！

如果您的公关尚未准备好合并，请通过前缀将其标记为正在进行中 WIP: 公关头衔，这样它就不会不经意地被批准和合并。

确保通过分配审阅者来请求审阅 jazzband/django-oauth-toolkit 。这将把评审分配给项目团队，成员将对其进行评审。与此同时，如果您发现需要更改的内容，或者是为了回应评论者的评论，您可以继续将提交添加到主题分支(并将它们推送到GitHub)。如果审阅者要求更改，则不需要关闭Pull并在进行更改后重新发布。只需在本地进行更改，将它们推送到GitHub，然后在Pull请求的讨论部分添加评论。

定期把上游的变化放到你的叉子里

定期将上游更改从master拉入到您的fork是一个很好的实践，事实上，如果您处理的是过时的代码，并且您的更改与master偏离太远，则必须拒绝拉入请求。

要引入上游更改：

git remote add upstream https://github.com/jazzband/django-oauth-toolkit.git
git fetch upstream

然后合并您获取的更改：：

git merge upstream/master

有关更多信息，请参见 GitHub Docs on forking the repository 。

备注

如果可能，请确保将您的提交重新定位到主服务器上，以便您的提交可以快进：我们会尽量避免 merge commits 当他们不是必须的时候。

如何让您的拉取请求被接受

我们真的想要您的代码，所以请遵循这些简单的指导方针，使过程尽可能顺利。

核对表

当您创建核对清单模板时，它会自动添加到您的PR中。确保你已经做了所有适用的步骤，并勾选它们，以表明你已经做了。这是创建您的公关时将看到的内容：：

Fixes #

## Description of the Change

## Checklist

- [ ] PR only contains one change (considered splitting up PR)
- [ ] unit-test added
- [ ] documentation updated
- [ ] `CHANGELOG.md` updated (only for user relevant changes)
- [ ] author name in `AUTHORS`

任何缺少核对清单项目的PR将不会被合并，如果它们被错误地合并，可能会被恢复。

去做测试吧！

Django OAuth工具包旨在支持不同的Python和Django版本，因此我们使用 tox 在多个配置上运行测试。在开发过程中的任何时候，至少在提交Pull请求之前，请通过以下方式运行测试套件：

tox

核心提交者要做的第一件事就是运行这个命令。任何未通过此测试套件的拉入请求都将是 immediately rejected 。

把测试加进去！

无论何时添加代码，您都必须添加测试。我们不能接受未经测试的代码，所以除非这是您之前与核心提交者讨论过的特殊情况，否则如果您的Pull请求减少了测试覆盖率，它将是 immediately rejected 。

您可以在本地使用 coverage 运行tox：：后的包

pip install coverage
coverage html -d mycoverage

打开 mycoverage/index.html 在您的浏览器中，您可以看到每个文件的覆盖摘要和覆盖详细信息。

没有必要在你提交公关后等待Codecov的投诉。

代码约定很重要

没有好的或坏的约定，只需遵循PEP8(为此运行一些lint工具)，没有人会争辩。试着阅读我们的代码，掌握有关方法和变量名称的总体理念，避免 black magics 为了提高可读性，请记住 simple is better than complex 。如果您觉得代码不直观，请添加注释。如果您认为一个函数不是微不足道的，那么可以添加一个文档字符串。

要查看您的代码格式是否通过测试，请使用：：

tox -e flake8

此页面的内容在很大程度上基于 django-admin2

维护人员核对表

以下注意事项旨在提醒项目维护人员和领导审查和合并PR以及发布新版本所需的步骤。

审查和合并PR

• 请确保公关描述包括 pull request template

• 确认PR模板中所有必需的核对表项目都在PR描述中显示为已完成，并且已实际完成。

• 仔细检查并要求进行任何必要的更改。

• 确保任何PR只提高代码覆盖率。

• 所有PR应由一个人(不是提交人)审查，并由另一个人合并。

错误合并的PR可能(不情愿地)由项目负责人恢复。

发布版本

只有项目主管才能 publish a release 到pypi.org和rtfd.io。这份清单是对所需步骤的提醒。

• 在计划新版本时，请创建 milestone 并将问题、PR等分配给该里程碑。

• 检查自上次发布以来的所有提交，并确认它们已正确记录在ChangeLog中。适当地使用指向文档的链接重新编写条目，以使其对用户有意义。

• 为更新的版本做最终公关：

  • CHANGELOG.md 以显示发行日期。

  • oauth2_provider/__init__.py to set __version__ = "..."

• 一旦最终的PR被合并，创建并推送用于发布的标签。您很快就会收到来自Jazzband的通知，通知您有两个Pypi包(源tgz和车轮)可用。在发布之前，请在本地下载这些文件。

• 做一件 tox -e build 并将下载并构建的车轮压缩和tgz文件解压缩到临时目录中，然后执行 diff -r 以确保它们具有相同的内容。(不幸的是，由于元数据中的时间戳，校验和不匹配，因此您需要比较所有文件。)

• 一旦对上面的比较结果感到满意，就可以向Pypi.org批准发布。