排版错误修复和简单的文档更改¶

如果您要修复一个非常简单的问题，例如更改文档中的一个词，首选的方法是使用 GitHub pull requests 提交补丁，无需 Trac 工单。

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

“认领”工单¶

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

因此，我们的政策是贡献者需要“认领”工单，以便让其他开发者知道某个特定错误或功能正在开发中。

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

• 使用您的 GitHub 帐户登录或在我们的工单系统中创建一个帐户。如果您有帐户但忘记了密码，您可以使用密码重置页面重置它。

• 如果该问题的工单还不存在，请在我们的工单跟踪器中创建一个。

• 如果该问题的工单已存在，请确保没有人认领它。为此，请查看工单的“由谁拥有”部分。如果分配给“没有人”，则可以认领。否则，其他人可能正在处理此工单。您可以寻找另一个错误/功能来处理，或者联系正在处理该工单的开发者以提供帮助。如果一个工单已经分配了数周或数月而没有任何活动，那么重新分配给自己可能是安全的。

• 如果您还没有登录，请点击工单页面左上角的“GitHub 登录”或“DjangoProject 登录”登录。登录后，您可以点击页面底部的“修改工单”按钮。

• 在“操作”部分点击“分配给”单选按钮认领工单。您的用户名将默认填写在文本框中。

• 最后点击底部的“提交更改”按钮保存。

贡献风格¶

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

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

• 如果代码添加了新功能或修改了现有功能的行为，则更改还应包含文档。

当您认为您的工作准备就绪进行审查时，请发送GitHub pull request。如果您由于某种原因无法发送 pull request，您也可以在 Trac 中使用补丁。使用此样式时，请遵循以下指南。

• 提交git diff命令返回的格式的补丁。

• 使用“附加文件”按钮将补丁附加到工单跟踪器中的工单。请不要将补丁放在工单描述或评论中，除非它是一个单行补丁。

• 使用.diff扩展名命名补丁文件；这将允许工单跟踪器应用正确的语法高亮显示，这非常有用。

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

• 确保您的代码满足我们贡献清单中的要求。

• 选中工单上的“有补丁”复选框，并确保未选中“需要文档”、“需要测试”和“补丁需要改进”复选框。这使得工单在开发仪表板上的“需要审查的补丁”队列中显示。

需要社区反馈的贡献¶

当补丁引入新的 Django 功能并做出某种设计决策时，需要更广泛的社区讨论。如果方法涉及弃用或引入重大更改，这一点尤其重要。

以下是获得社区反馈的不同方法。

弃用功能¶

Django 中的代码可能由于以下几个原因被弃用：

• 如果某个功能以向后不兼容的方式进行了改进或修改，则旧功能或行为将被弃用。

• 有时，Django 会包含一个 Python 库的反向移植，该库未包含在 Django 当前支持的 Python 版本中。当 Django 不再需要支持不包含该库的旧版 Python 时，该库将在 Django 中被弃用。

如同弃用策略中所述，Django 首次弃用某个功能（A.B）的版本应该在调用该弃用功能时引发 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) as ctx:
        # invoke deprecated behavior
        ...
    self.assertEqual(ctx.filename, __file__)

重要的是，在没有警告引用的代码上方添加 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,
        stacklevel=2,
    )
    old_private_helper()
    ...

最后，需要对 Django 的文档进行一些更新。

1. 如果已对现有功能进行文档记录，请使用 .. deprecated:: A.B 注释在文档中将其标记为已弃用。如有必要，请包含简短说明和升级路径说明。

2. 在当前发行说明（docs/releases/A.B.txt）的“在 A.B 中弃用的功能”标题下添加对弃用行为的描述以及适用的升级路径。

3. 在弃用时间轴（docs/internals/deprecation.txt）的相应版本下添加一个条目，描述将要移除的代码。

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

JavaScript 贡献¶

有关 JavaScript 贡献的信息，请参阅JavaScript 修补程序文档。

优化补丁¶

旨在提高性能的补丁应提供基准测试，展示补丁前后产生的影响，并分享供审阅者复现的命令。

贡献清单¶

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

正在寻找要审查的补丁？请查看 Django 开发面板 的“需要审查的补丁”部分。

希望您的拉取请求得到审查？请确保票证上的 Trac 标志已设置，以便票证显示在该队列中。