Django/docs/3.0.x/internals/contributing/writing-code/submitting-patches

提交补丁

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

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

如果您正在修复一个非常微不足道的问题，例如更改文档中的一个词，提供补丁的首选方法是使用 GitHub 拉取请求，而无需使用 Trac 票证。

有关如何使用拉取请求的更多详细信息，请参阅 使用 Git 和 GitHub 。

“索取”门票

在全球有数百名贡献者的开源项目中，有效管理沟通非常重要，这样工作就不会重复，贡献者才能尽可能高效。

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

如果你已经确定了你想要做出的贡献并且你有能力修复它（根据你的编码能力、Django 内部知识和时间可用性来衡量），请按照以下步骤声明它：

• 使用您的GitHub帐户登录或在我们的票务系统中创建一个帐户。 如果您有账户但忘记了密码，您可以使用密码重置页面重置它。
• 如果此问题的工单尚不存在，请在我们的 工单跟踪器 中创建一张工单。
• 如果此问题的票证已经存在，请确保没有其他人声明过它。 为此，请查看票证的“所有者”部分。 如果它被分配给“没有人”，那么它就可以被认领。 否则，其他人可能正在处理此票证。 要么找到另一个要处理的错误/功能，要么联系处理故障单的开发人员以提供帮助。 如果一张票已被分配了数周或数月而没有任何活动，则将其重新分配给自己可能是安全的。
• 登录您的帐户，如果您还没有，请单击票务页面左上角的“GitHub 登录”或“DjangoProject 登录”。
• 通过单击页面底部附近“操作”下的“分配给我自己”单选按钮索取票证，然后单击“提交更改”。

笔记

Django 软件基金会要求任何为 Django 贡献的不仅仅是一个简单补丁的人签署并提交 贡献者许可协议 ，这确保了 Django 软件基金会对所有贡献拥有明确的许可，从而为所有用户提供明确的许可.

购票人的责任

一旦您申领了一张罚单，您就有责任以合理的方式及时处理该罚单。 如果您没有时间处理它，要么取消它，要么首先不要声明它！

如果某张已领取的门票在一两周内没有任何进展迹象，另一位开发人员可能会要求您放弃该门票领取，以便它不再被垄断，其他人可以领取它。

如果您已经申领了一张票并且需要很长时间（几天或几周）来编码，请通过在票上发表评论来让每个人都了解最新情况。 如果您不提供定期更新，并且您不回应进度报告的请求，您对票的索赔可能会被撤销。

一如既往，多交流总比少交流好！

应该申领哪些门票？

当然，在某些情况下，通过索取门票的步骤是矫枉过正的。

对于小的更改，例如文档中的拼写错误或只需几分钟即可修复的小错误，您无需跳过索取票的麻烦。 直接提交您的补丁就大功告成了！

当然， 总是 可以接受，无论是否有人声称，如果您碰巧准备好补丁，则将补丁提交到票证。

补丁样式

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

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

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

如果由于某种原因无法发送 pull request，也可以在 Trac 中使用补丁。 使用此样式时，请遵循以下准则。

• 以 git diff 命令返回的格式提交补丁。
• 使用“附加文件”按钮将补丁附加到 票务跟踪器 中的票证。 请不要将补丁放入票证描述或评论中，除非它是单行补丁。
• 将补丁文件命名为 .diff 扩展名； 这将使票证跟踪器应用正确的语法突出显示，这非常有用。

无论您提交作品的方式如何，请按照以下步骤操作。

• 确保您的代码满足我们的 补丁审查清单 中的要求。
• 检查票证上的“有补丁”框，并确保未选中“需要文档”、“需要测试”和“补丁需要改进”框。 这使得故障单出现在 开发仪表板 上的“需要审查的补丁”队列中。

重要补丁

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

如果您提供了一个重要的补丁，请提供已经在 django-developers 上讨论过替代方案的证据。

如果您不确定您的补丁是否应该被视为非平凡，请在票证上征求意见。

弃用功能

不推荐使用 Django 中的代码有几个原因：

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

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

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

1. 在特定测试中：

   from django.test import ignore_warnings
   from django.utils.deprecation import RemovedInDjangoXXWarning
   
   @ignore_warnings(category=RemovedInDjangoXXWarning)
   def test_foo(self):
       ...

2. 对于整个测试用例：

   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

最后，对 Django 的文档进行了一些更新：

1. 如果记录了现有功能，请使用 .. deprecated:: A.B 注释在文档中将其标记为已弃用。 如果适用，请包括有关升级路径的简短说明和注释。
2. 在当前版本说明 (docs/releases/A.B.txt) 的“AB 中弃用的功能”标题下添加对弃用行为的描述和升级路径（如果适用）。
3. 在相应版本下的弃用时间线 (docs/internals/deprecation.txt) 中添加一个条目，描述将删除哪些代码。

完成这些步骤后，您就完成了弃用。 在每个功能版本中，与新版本匹配的所有RemovedInDjangoXXWarning都被删除。

JavaScript 补丁

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

补丁审查清单

使用此清单检查拉取请求。 如果您正在审查不是您自己的拉取请求并且它通过了以下所有标准，请将相应 Trac 票证上的“分类阶段”设置为“准备签入”。 如果您对拉取请求留下了改进意见，请根据您的审查结果在 Trac 票证上勾选相应的标志：“补丁需要改进”、“需要文档”和/或“需要测试”。 在时间和兴趣允许的情况下，提交者会对“准备签入”票据进行最终审查，如果需要做进一步的工作，他们将提交补丁或将其退回“已接受”。 如果您想成为提交者，对补丁进行彻底审查是赢得信任的好方法。

正在寻找要审查的补丁？ 查看 Django 开发仪表板 的“需要审查的补丁”部分。 想要审核您的补丁？ 确保设置了票证上的 Trac 标志，以便票证出现在该队列中。

文档

• 文档构建时是否没有任何错误（make html 或 Windows 上的 make.bat html，来自 docs 目录）？
• 文档是否遵循 Writing documentation 中的写作风格指南？
• 是否有任何 拼写错误 ？

错误

• 是否有适当的回归测试（在应用修复之前测试应该失败）？
• 如果是 有资格向后移植 到稳定版 Django 的错误，那么 docs/releases/A.B.C.txt 中是否有发行说明？ 仅适用于 master 分支的错误修复不需要发行说明。

新功能

• 是否有测试可以“锻炼”所有新代码？
• docs/releases/A.B.txt 中是否有发行说明？
• 是否有该功能的文档，并且 是否用 .. versionadded:: A.B 或 .. versionchanged:: A.B 进行了适当的注释 ？

弃用功能

请参阅 弃用功能 指南。

所有代码更改

• 编码风格 是否符合我们的准则？ 是否有任何 flake8 错误？
• 如果更改以任何方式向后不兼容，发行说明 (docs/releases/A.B.txt) 中是否有说明？
• Django 的测试套件通过了吗？

所有门票

• 拉取请求是否是单个压缩提交，其消息遵循我们的 提交消息格式 ？
• 您是补丁作者和新贡献者吗？ 请将您自己添加到 AUTHORS 文件中并提交 贡献者许可协议 。