提交补丁 — Django 文档
提交补丁
我们总是感谢 Django 代码的补丁。 事实上，与没有补丁的错误报告相比，带有相关补丁的错误报告将更快地得到修复 far。
错字修复和琐碎的文档更改
如果您正在修复一个非常微不足道的问题，例如更改文档中的一个词，提供补丁的首选方法是使用 GitHub 拉取请求，而无需使用 Trac 票证。
有关如何使用拉取请求的更多详细信息，请参阅 使用 Git 和 GitHub 。
“索取”门票
在全球有数百名贡献者的开源项目中，有效管理沟通非常重要，这样工作就不会重复，贡献者才能尽可能高效。
因此，我们的政策是让贡献者“申领”门票，以便让其他开发人员知道正在处理特定的错误或功能。
如果你已经确定了你想要做出的贡献并且你有能力修复它（根据你的编码能力、Django 内部知识和时间可用性来衡量），请按照以下步骤声明它：
- 使用您的GitHub帐户登录或在我们的票务系统中创建一个帐户。 如果您有账户但忘记了密码，您可以使用密码重置页面重置它。
- 如果此问题的工单尚不存在，请在我们的 工单跟踪器 中创建一张工单。
- 如果此问题的票证已经存在，请确保没有其他人声明过它。 为此，请查看票证的“所有者”部分。 如果它被分配给“没有人”，那么它就可以被认领。 否则，其他人可能正在处理此票证。 要么找到另一个要处理的错误/功能，要么联系处理故障单的开发人员以提供帮助。 如果一张票已被分配了数周或数月而没有任何活动，则将其重新分配给自己可能是安全的。
- 登录您的帐户，如果您还没有，请单击票务页面左上角的“GitHub 登录”或“DjangoProject 登录”。
- 通过单击页面底部附近“操作”下的“分配给我自己”单选按钮索取票证，然后单击“提交更改”。
笔记
Django 软件基金会要求任何为 Django 贡献的不仅仅是一个简单补丁的人签署并提交 贡献者许可协议 ，这确保了 Django 软件基金会对所有贡献拥有明确的许可，从而为所有用户提供明确的许可.
购票人的责任
一旦您申领了一张罚单，您就有责任以合理的方式及时处理该罚单。 如果您没有时间处理它，要么取消它，要么首先不要声明它！
如果某张已领取的门票在一两周内没有任何进展迹象，另一位开发人员可能会要求您放弃该门票领取，以便它不再被垄断，其他人可以领取它。
如果您已经申领了一张票并且需要很长时间（几天或几周）来编码，请通过在票上发表评论来让每个人都了解最新情况。 如果您不提供定期更新，并且您不回应进度报告的请求，您对票的索赔可能会被撤销。
与往常一样，多交流好过少交流！
应该发布哪类工单？
当然，在某些情况下，通过索取门票的步骤是矫枉过正的。
对于小的更改，例如文档中的拼写错误或只需几分钟即可修复的小错误，您无需跳过索取票的麻烦。 只需提交您的补丁即可完成。
当然， 总是 可以接受，无论是否有人声称，如果您碰巧准备好补丁，则将补丁提交到票证。
补丁的风格
确保您所做的任何贡献至少满足以下要求：
- 修复问题或添加功能所需的代码是补丁的重要部分，但不是唯一的部分。 一个好的补丁还应该包括 回归测试 以验证已修复的行为并防止问题再次出现。 此外，如果某些工单与您编写的代码相关，请在测试中的某些注释中提及工单编号，以便在您提交补丁并关闭工单后可以轻松追溯相关讨论。
- 如果与修补程序关联的代码添加了新功能或修改了现有功能的行为，则该修补程序还应包含文档。
当您认为您的工作已准备好接受审查时，请发送 GitHub 拉取请求 。 请先使用我们的 补丁审查清单 自己审查补丁。
如果由于某种原因无法发送 pull request，也可以在 Trac 中使用补丁。 使用此样式时，请遵循以下准则。
- 以
git diff命令返回的格式提交补丁。 - 使用“附加文件”按钮将补丁附加到 票务跟踪器 中的票证。 请不要将补丁放入票证描述或评论中，除非它是单行补丁。
- 将补丁文件命名为
.diff扩展名； 这将使票证跟踪器应用正确的语法突出显示，这非常有用。
无论您以何种方式提交工作成果，请按照以下步骤操作。
- 确保您的代码满足我们的 补丁审查清单 中的要求。
- 检查票证上的“有补丁”框，并确保未选中“需要文档”、“需要测试”和“补丁需要改进”框。 这使得故障单出现在 开发仪表板 上的“需要审查的补丁”队列中。
不一般的补丁
“非平凡”补丁不仅仅是一个简单的错误修复。 这是一个引入 Django 功能并做出某种设计决策的补丁。
如果您提供了一个重要的补丁，请提供已经在 django-developers 上讨论过替代方案的证据。
如果您不确定您的补丁是否应该被视为重要的，请直接询问。
弃用功能
Sphinx中的代码可能会被弃用，这有两个原因：
- 如果某个功能以向后不兼容的方式进行了改进或修改，则旧功能或行为将被弃用。
- 有时 Django 会包含一个 Python 库的向后移植，该库不包含在 Django 当前支持的 Python 版本中。 当 Django 不再需要支持不包含该库的旧版 Python 时，该库将在 Django 中被弃用。
正如 弃用政策 所描述的，弃用功能 (A.B) 的第一个 Django 版本应该引发 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最后，对 Django 的文档进行了一些更新：
- 如果记录了现有功能，请使用
.. deprecated:: A.B注释在文档中将其标记为已弃用。 如果适用，请包括有关升级路径的简短说明和注释。 - 在当前版本说明 (
docs/releases/A.B.txt) 的“AB 中弃用的功能”标题下添加对弃用行为的描述和升级路径（如果适用）。 - 在相应版本下的弃用时间线 (
docs/internals/deprecation.txt) 中添加一个条目，描述将删除哪些代码。
完成这些步骤后，您就完成了弃用。 在每个功能版本中，与新版本匹配的所有RemovedInDjangoXXWarning都被删除。
补丁审查清单
使用此清单检查拉取请求。 如果您正在审查不是您自己的拉取请求并且它通过了以下所有标准，请将相应 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 的测试套件通过了吗？
