提交补丁

提交补丁

我们总是感谢Django代码的补丁。确实，具有相关补丁的错误报告将比没有补丁的错误报告更快地得到修复。

错字修复和琐碎的文档更改

如果您正在修复一个非常微不足道的问题，例如更改文档中的一个单词，推荐的方法是使用 GitHub 提交拉取请求，而无需使用 Trac 工单。

有关如何使用拉取请求的更多详细信息，请参见:doc:working-with-git

“发布”工单

在一个全球有数百个贡献者的开源项目中，有效地管理沟通以避免重复工作并尽可能提高贡献者的效率是非常重要的。

因此，我们的政策是供贡献者“发布”工单，以便让其他开发人员知道正在处理特定的错误或功能。

如果您确定了要做出的贡献并且有能力解决（通过编程能力，Django内核知识水平和时间可用性来衡量），请按照以下步骤进行发表：

使用您的 GitHub 帐户登录或在我们的工单系统中创建一个帐户。如果您有帐户但忘记了密码，可以使用密码重置页面进行重置。
如果尚无此问题的工单，请在我们的 ticket tracker 工单追踪系统中创建一个。
如果此问题已有相关工单，请确保没有其他人认领。要做到这一点，查看工单的 “ Owned by “（负责人）部分。如果它被分配给了 “ nobody “（无人认领），那么它可以被认领。否则，可能已经有其他人正在处理此工单。您可以选择另一个错误或功能来处理，或者联系负责此工单的开发人员提供帮助。如果一个工单在数周或数月内没有任何活动，那么将其重新分配给自己可能是安全的。
如果您尚未登录，请点击工单页面左上方的 “ GitHub 登录” 或 “ DjangoProject 登录” 来登录您的账户。
通过点击页面底部附近的 “ Action “ 下方的 “ assign to myself “ 单选按钮来认领工单，然后点击 “ Submit changes “ 提交更改。

备注

Django软件基金会要求对Django贡献不小的补丁的人签署并提交 Contributor License Agreement 贡献者许可协议，以确保Django软件基金会对所有贡献都拥有明确的许可，从而为所有用户提供明确的许可。

工单发表者的责任

发布工单后，您有责任以合理及时的方式处理该工单。如果您没有时间来处理它，请先取消发布或不发布它！

如果一两周内没有任何关于特定已发布工单的进展迹象，则另一位开发人员可能会要求您放弃该发布了的工单，以使其不再被垄断，而其他人也可以发布。

如果您已发布工单，并且要花很长时间（几天或几周）编写代码，请通过在工单上发布评论来使每个人都保持最新状态。如果您不提供定期更新，并且不响应进度报告的请求，则您对工单的要求可能会被撤消。

与往常一样，多交流好过少交流！

应该发布哪类工单？

在某些情况下，执行认领工单的步骤可能过于繁琐。

对于一些小的改动，比如文档中的错别字或只需要几分钟修复的小错误，您无需进行认领工单的繁琐步骤。直接提交您的补丁即可完成！

如果您已经准备好补丁，始终可以向工单提交补丁，无论是否有其他人已经认领了该工单。

补丁的风格

确保您所做的任何贡献至少满足以下要求：

解决问题或添加功能所需的代码是补丁的重要组成部分，但不是唯一的部分。一个好的补丁程序还应该包括一个 regression test 1 回归测试以验证已修复的行为并防止问题再次出现。另外，如果某些工单与您编写的代码相关，请在测试中的一些注释中提及工单编号，以便在提交补丁程序并关闭工单后可以轻松地追溯相关的讨论。
如果与修补程序关联的代码添加了新功能或修改了现有功能的行为，则该修补程序还应包含文档。

当您认为您的工作已经准备好进行审查时，请发送 GitHub 拉取请求。请首先使用我们的补丁审查清单自行审查补丁。

如果由于某种原因无法发送拉取请求，您还可以在 Trac 中使用补丁。在使用这种方式时，请遵循以下准则。

请以 git diff 命令返回的格式提交补丁。
使用“附加文件”按钮将补丁附加到 ticket tracker 工单跟踪系统中的工单上。除非是单行补丁，否则请不要将补丁放入工单描述或注释中。
用扩展名 .diff 命名补丁文件；这将使工单跟踪系统应用正确的语法突出显示，这非常有帮助。

无论您以何种方式提交工作成果，请按照以下步骤操作。

确保您的代码满足我们的补丁审查清单中的要求。
勾选工单上的 “Has patch” 复选框，并确保 “Needs documentation”、”Needs tests” 和 “Patch needs improvement” 复选框没有被勾选。这将使工单显示在 Development dashboard 的 “Patches needing review” 队列中。

不一般的补丁

一个“非微小”的补丁是指不仅仅是修复小错误的补丁。它是一个引入 Django 功能并做出某种设计决策的补丁。

如果您提供了一个复杂的补丁，请包含证据表明曾在 Django 论坛或 django-developers 列表上讨论过替代方案。

如果你不确定你的补丁是否应该被认为是非微小的，请在票务系统上征求意见。

弃用一个功能

Django 中的代码可能被弃用的原因有几个：

如果一个功能在与向后兼容性不兼容的方式下进行了改进或修改，旧的功能或行为将被弃用。
有时，Django 会包含一个 Python 库的后移版本，而该库在 Django 当前支持的 Python 版本中不包含。当 Django 不再需要支持不包含该库的旧版本 Python 时，该库将在 Django 中被弃用。

正如弃用政策所描述的那样，第一个弃用某项功能的 Django 版本（A.B）在调用被弃用功能时应该引发一个 RemovedInDjangoXXWarning 警告（其中 XX 是将要删除该功能的 Django 版本）。假设我们有良好的测试覆盖率，在启用警告的情况下，这些警告将在运行测试套件时转换为错误：python -Wa runtests.py。因此，在添加 RemovedInDjangoXXWarning 时，您需要消除或消除运行测试时生成的任何警告。

第一步是通过 Django 自身去除对被弃用行为的使用。接下来，您可以使用 ignore_warnings 装饰器来消除测试中实际测试被弃用行为的警告，可以在测试或类级别使用它：

在一个特定的测试中：

``` from django.test import ignore_warnings from django.utils.deprecation import RemovedInDjangoXXWarning

@ignore_warnings(category=RemovedInDjangoXXWarning)
def test_foo(self):
    ...
```

对于整个测试用例：

``` from django.test import ignore_warnings from django.utils.deprecation import RemovedInDjangoXXWarning

@ignore_warnings(category=RemovedInDjangoXXWarning)
class MyDeprecatedTests(unittest.TestCase):
    ...
```

您还应该为弃用警告添加一个测试：

from django.utils.deprecation import RemovedInDjangoXXWarning
def test_foo_deprecation_warning(self):
    msg = "Expected deprecation message"
    with self.assertWarnsMessage(RemovedInDjangoXXWarning, msg):
        # invoke deprecated behavior
        ...

重要的是在没有警告引用但在弃用结束时需要更改或删除的代码上方包含一个 RemovedInDjangoXXWarning 注释。这可能包括已添加以保持先前行为的钩子，或在弃用结束时不再需要或未使用的独立项目。例如：

import warnings
from django.utils.deprecation import RemovedInDjangoXXWarning
# RemovedInDjangoXXWarning.
def old_private_helper():
    # Helper function that is only used in foo().
    pass
def foo():
    warnings.warn(
        "foo() is deprecated.",
        category=RemovedInDjangoXXWarning,
    )
    old_private_helper()
    ...

最后，还有一些更新需要进行，以更新 Django 的文档：

如果现有功能已经在文档中记录，请使用 .. deprecated:: A.B 注解在文档中标记它为已弃用。如果适用，包括一个简短的描述和有关升级路径的说明。
将已弃用行为的描述以及升级路径（如果适用）添加到当前版本的发行说明（docs/releases/A.B.txt）中，放在 “Features deprecated in A.B” 标题下。
在适当的版本下，将一个条目添加到弃用时间表（docs/internals/deprecation.txt）中，描述将要被移除的代码。

一旦完成了这些步骤，你就完成了弃用过程。在每个特性发布中，与新版本匹配的所有 RemovedInDjangoXXWarning 都会被移除。

JavaScript 补丁

有关 JavaScript 补丁的信息，请参阅 JavaScript 补丁文档。

补丁审查清单

使用此清单来审查拉取请求。如果您正在审查一个不是您自己的拉取请求，并且它满足下面的所有标准，请将相应的 Trac 工单上的 “Triage Stage” 设置为 “Ready for checkin”。如果您已经在拉取请求上留下了改进的评论，请根据您的审查结果在 Trac 工单上选择适当的标志：”Patch needs improvement”、”Needs documentation” 和/或 “Needs tests”。根据时间和兴趣，合并者会对 “Ready for checkin” 的工单进行最终审查，并将补丁提交或将其推回 “Accepted”，如果需要进一步的工作。如果您想成为合并者，认真审查补丁是赢得信任的好方法。

寻找需要审查的补丁吗？请查看 Django 开发仪表板中的 “Patches needing review” 部分。希望您的补丁得到审查吗？请确保工单上的 Trac 标志已设置，以便工单出现在该队列中。

文档

文档是否能够在没有任何错误的情况下构建（从 docs 目录执行 make html，或者在 Windows 上执行 make.bat html）？
文档是否遵循编写文档中的写作风格指南？
是否存在任何拼写错误？

错误

是否有适当的回归测试（在应用修复之前，测试应该失败）？
如果是一个符合 Django 稳定版本的可回退的 bug，是否在 docs/releases/A.B.C.txt 中有一份发行说明？只会应用到主分支的 bug 修复不需要发行说明。

新功能

是否有测试来 “运行” 所有新代码？
是否在 docs/releases/A.B.txt 中有一份发行说明？
是否为该功能提供了文档，并且文档是否适当地使用了 .. versionadded:: A.B 或 .. versionchanged:: A.B 进行了注释？

弃用一个功能

请参阅弃用一个功能指南。

所有代码更改

代码风格是否符合我们的指南？是否有任何 black、blacken-docs、flake8 或 isort 错误？您可以安装 pre-commit 钩子来自动捕获这些错误。
如果更改在任何方面不向后兼容，是否在发行说明（docs/releases/A.B.txt）中有说明？
Django 的测试套件是否通过？

所有工单

拉取请求是否是一个合并的提交，其提交消息符合我们的提交消息格式？
您是否是补丁的作者并且是新的贡献者？请将自己添加到 AUTHORS 文件并提交 Contributor License Agreement。