贡献

布设

GitHub上的分叉

在执行任何其他操作之前，请登录/注册GitHub并从 GitHub project 。

在本地克隆你的叉子

如果您安装了GIT-SCM，现在可以使用以下命令行参数克隆您的GIT存储库，其中<my-gitHub-name>是您在GitHub上的帐户名：

git clone git@github.com/<my-github-name>/oauthlib.git

问题！

未完成的OAuthLib功能请求和错误列表可以在我们的GitHub上的上找到 issue tracker 。选择一个你认为你可以完成的未分配的问题，添加一个你正在尝试这样做的评论，不久之后，与你的GitHub ID匹配的你自己的个人标签就会被分配给那个问题。

请随意提出未被描述的问题！

Oauthlib社区规则

Oauthlib是一个开发者社区，它遵循一套非常简单的规则。

行为规范

这个项目坚持一个 Code of Conduct 基于Django。作为社区成员，你必须阅读并同意它。

欲了解更多信息，请联系我们和/或访问原件 Django Code of Conduct 主页。

功勋守则

请阅读社区的 Code of Merit 。每一位贡献者都会知道他们为这个项目做出贡献的真正目的。

设置主题分支并生成拉取请求

虽然在问题中提供有用的代码片段很方便，但作为开发人员，最好提交拉请求。通过提交拉取请求，您对OAuthlib的贡献将由Github记录下来。

在GIT中，最好将每个主题或特性隔离到一个“主题分支”中。虽然单独提交允许您控制对代码进行多小的单独更改，但分支是将与一个功能相关的一组提交组合在一起的一种很好的方法，或者在您可能同时处理多个主题时隔离不同的工作。

虽然需要一些经验才能对如何分解提交有正确的了解，但主题分支的范围应该限制在单个 issue 提交给问题跟踪器。

此外，由于GitHub将拉入请求与特定分支机构进行绑定和同步，因此它是 ONLY 一次可以提交多个补丁的方式。如果您从主分支提交Pull，则在没有添加到Pull中的那些Pull之前，您不能向您的主提交更多的Pull。

要创建主题分支，最简单的方法是使用 -b 参数为 git checkout **

git checkout -b fix-broken-thing
Switched to a new branch 'fix-broken-thing'

您应该为您的分支使用足够详细的名称，以便清楚它是关于什么的。现在，您可以提交更改并定期合并到上游主服务器中，如下所述。

当您准备好生成Pull请求时，无论是用于初步审查，还是考虑合并到项目中，您必须首先将您的本地主题分支推送回GitHub：：

git push origin fix-broken-thing

现在，当你转到GitHub上的分支时，你会看到这个分支列在“源”选项卡下面，上面写着“切换分支”。继续，从该列表中选择您的主题分支，然后单击“拉入请求”按钮。

您可以在此处添加有关您的分支机构的评论。如果这是对提交的问题的回应，最好在这个初始评论中添加一个指向该问题的链接。回购经理将收到您的拉取请求的通知，并将对其进行审查(有关最佳实践，请参阅下文)。请注意，您可以继续将提交添加到主题分支(并将它们推送到GitHub)，无论是您发现需要更改的内容，还是响应审阅者的评论。如果审阅者要求更改，则不需要关闭Pull并在进行更改后重新发布。只需在本地进行更改，将它们推送到GitHub，然后在Pull请求的讨论部分添加评论。

把上游的变化放到你的叉子上

定期将上游更改从主应用程序引入到您的分支程序中是至关重要的。最糟糕的事莫过于花了几天的时间努力拉取请求，结果却被拒绝，因为它与师父的分歧太大了。

要引入上游更改：

git remote add upstream https://github.com/oauthlib/oauthlib.git
git fetch upstream

在合并之前，请检查日志以确保您确实想要更改：

git log upstream/master

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

git merge upstream/master

欲了解更多信息，请访问https://help.github.com/fork-a-repo/。

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

我们想要你的投降。但我们也希望为我们的用户和社区提供稳定的体验。遵循这些规则，你应该会毫不费力地成功！

去做测试吧！

在提交拉取请求之前，请通过以下方式从项目根运行整个OAuthLib测试套件：

$ pytest

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

测试多个版本的Python

OAuthLib支持Python3.8+和PyPy 3。一次方便地测试所有版本可以使用 Tox 。

$ tox

毒理测试要求你有 virtualenv 安装的版本以及各自的python版本。我们建议您使用 pyenv 来安装这些版本的Python。

我们建议对我们支持的每个Python版本使用最新的补丁版本，并使用最新的PyPy版本。下面的版本可能不是最新的。

$ pyenv install -l # check which versions you want to use
$ pyenv install 3.8.18
$ pyenv install 3.11.7
$ pyenv install pypy3.10-7.3.13

测试上游应用程序

请记住，OAuthLib被几个第三方项目使用。如果您认为您提交了一个突破性的更改，请确认其他项目版本不受影响。

$ make

如果您添加代码，请添加测试！

我们痛苦地认识到，没有测试的代码是不可靠的。如果您的Pull请求因为缺少测试而减少了我们的测试覆盖率，那么它将是 rejected 。

此外，请尽可能保持您的测试简单。复杂的测试最终需要自己的测试。我们宁愿看到跨测试方法的重复断言，也不愿看到巧妙的实用方法神奇地确定在特定阶段需要哪些断言。记住： Explicit is better than implicit 。

不要将代码更改与空格清理混为一谈

如果您更改了两行代码并更正了一个文件中的200行空格问题，则该拉入请求上的diff在功能上是不可读的，并且将是 rejected 。空格清理需要在其自己的拉取请求中。

将您的拉式请求限制在单一问题上

OauthLib Pull请求应该尽可能小/原子。拉取请求中的大范围更改将是 rejected ，并带有注释以隔离拉取请求中的特定代码。下面是一些示例：

  1. 如果您在文档中进行拼写更正，请不要修改任何Python代码。

  2. 如果要添加新模块，请不要‘ cleanup ‘其他模块。在另一个拉取请求中进行清理。

  3. 更改模块的任何属性，例如对文件的权限，都应该在它自己的Pull请求中进行，并说明原因。

遵循PEP-8并保持您的代码简单！

记住 Python 的禅宗：：

>>> python -c 'import this'

请尽可能使您的代码保持干净和直观。当我们看到一个或两个以上以 _my_special_function or things like `_ _Builtins__.object=str`我们开始担心。与其试着去理解你的杰作，我们只需要 reject 并发送了一份简化请求。

此外，像素短缺已经结束。我们希望看到：

  • package instead of pkg

  • grid instead of g

  • my_function_that_does_things instead of mftdt

一定要写好文档！

文档不仅很好，而且很棒--对于像OAuthlib这样的大型包来说，它是必不可少的。请确保下一个阅读您的函数/方法的人能够快速理解它的作用和方式。此外，请确保传递给每个函数的参数也有正确的文档记录。

该项目有这些目标/对文档字符串的请求，旨在使自动生成的文档更清晰地阅读：

  1. 函数中的每个参数都应该在文档字符串中列出，并且应该以它们在函数本身中出现的相同顺序出现。

  2. 如果不确定参数描述的最佳措辞，请将其留空，但仍要包括 :param foo: 排队。这将使维护人员更容易查看和编辑。

  3. 尽可能使用此项目文档中其他地方出现的参数的现有标准化描述。例如, request 在整个项目中被用作参数，描述为“OAuthlib请求”。-没有理由在您的函数中以不同的方式描述它。参数描述应该是以句点结尾的句子--即使它只是两个单词。

  4. 在可能的情况下，包括 type 参数的声明。例如，“请求”参数通常伴随着 :type request: oauthlib.common.Request 。该类型应为对象类型引用，并且不应以句点结尾。

  5. 如果存在文本文档字符串(推荐)，请使用单个空行分隔文档字符串和参数。

  6. 在引用类函数时，请使用反号。

综合示例

def foo(self, request, client, bar=None, key=None):
        """
        This method defines framework for `MAC Access Authentication`_ RFC.

        This method checks the `key` against the `client`. The `request` is
        passed to maintain context.

        Example MAC Authorization header, linebreaks added for clarity

        Authorization: MAC id="h480djs93hd8",
                                           nonce="1336363200:dj83hs9s",
                                           mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

        :param request: OAuthlib request.
        :type request: oauthlib.common.Request
        :param client: User's defined Client object, see ``.authenticate_client``.
        :param bar: Another example.
        :param key: Another param.
        :return: Explanation of return value and type

        .. _`MAC Access Authentication`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
        """

如何检查、测试和完成拉入请求

首先，我们将代码放入本地分支：：

git remote add <submitter-github-name> git@github.com:<submitter-github-name>/oauthlib.git
git fetch <submitter-github-name>
git checkout -b <branch-name> <submitter-github-name>/<branch-name>

然后，我们运行测试：

tox

我们以非FastForward合并结束(以保留分支历史)，并推送到GitHub：：

git checkout master
git merge --no-ff <branch-name>
git push upstream master

赞助商

OAuthlib项目接受赞助。

作为赞助商，您可以通过点击https://github.com/oauthlib/oauthlib主页中的“赞助商”按钮来参与。

作为一名贡献者，你可以坚持赞助计划。您可以通过将您的名字添加到 .github/FUNDING.yml 文件。