Skip to main content

提交修补程序

我们总是感谢Django的代码补丁。事实上,具有相关补丁的错误报告将比没有补丁的错误报告更快地得到固定的 far

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

如果你正在修复一个非常微不足道的问题,例如更改文档中的一个单词,提供补丁的首选方式是使用GitHub pull请求,没有Trac票。

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

“索赔”门票

在一个开源项目中,世界各地有数百个贡献者,重要的是有效地管理通信,使工作不会重复,贡献者可以尽可能有效。

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

如果你已经确定了你想要的贡献,并且你有能力修正它(根据你的编码能力,Django内部的知识和时间可用性衡量),通过以下步骤声明:

  • Login using your GitHub accountcreate an account 在我们的票系统。如果您有帐户,但忘记了密码,则可以使用 password reset page 重置密码。

  • 如果此问题的故障单尚不存在,请在我们的 ticket tracker 中创建一个故障单。

  • 如果此问题的故障单已存在,请确保没有人声明。为此,请查看故障单的“所有者”部分。如果它被分配给“nobody”,那么它可以声明。否则,其他人可能正在这张票。找到另一个错误/功能来工作,或联系工作在票证的开发人员提供您的帮助。如果一张票已经分配了几个星期或几个月没有任何活动,它可能安全重新分配给自己。

  • 如果您尚未登录,请通过点击机票页面左上方的“GitHub登录”或“DjangoProject登录”来登录。

  • 通过点击页面底部附近“操作”下的“分配给我自己”单选按钮来声明该票,然后点击“提交更改”。

注解

Django软件基金会要求任何人贡献超过一个小的补丁Django签名和提交 Contributor License Agreement,这确保Django软件基金会有明确的许可证所有捐款允许所有用户的清晰的许可证。

机票代理人的责任

一旦您申领了机票,您有责任以合理及时的方式处理该机票。如果你没有时间工作,要么取消声明它,要么不首先声明它!

如果在一周或两周的特定索赔机票上没有任何进展迹象,另一个开发商可能会要求您放弃机票索赔,使其不再被垄断,其他人可以索取。

如果您已经声明了一张票,并且代码需要很长时间(几天或几周),请通过在票证上发布评论来更新每个人。如果您不定期提供更新,并且您没有回应进度报告的请求,您对该机票的索赔可能会被撤销。

和往常一样,更多的沟通比更少的沟通更好!

应该索取哪些车票?

当然,在某些情况下,通过申请车票的步骤是过度的。

在小的变化的情况下,例如在文档中的拼写错误或小错误,只需要几分钟来修复,你不需要跳过索赔机票的圈。只需提交您的补丁并完成它。

当然,always 是可以接受的,无论有人是否声称,如果你碰巧有补丁准备好,提交补丁。

补丁样式

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

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

  • 如果与修补程序相关联的代码添加了新功能或修改了现有功能的行为,则修补程序还应包含文档。

当您认为您的工作准备好接受审核时,请发送 一个GitHub pull请求。请先使用我们的 补丁审查清单 自行检查补丁。

如果由于某种原因您不能发送拉取请求,您也可以在Trac中使用补丁。使用此样式时,请遵循以下准则。

  • git diff 命令返回的格式提交修补程序。

  • 使用“附加文件”按钮将修补程序附加到 ticket tracker 中的故障单。请 don’t 将补丁放在票证描述或注释中,除非它是单行补丁。

  • 将补丁文件命名为 .diff 扩展名;这将使票据跟踪器应用正确的语法高亮,这是非常有用的。

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

  • 确保您的代码符合我们的 补丁审查清单 中的要求。

  • 检查故障单上的“有补丁”框,并确保未选中“需要文档”,“需要测试”和“补丁需求改进”框。这使得票券出现在 Development dashboard 上的“需要审查的补丁”队列中。

非平凡补丁

“非平凡”补丁是一个不只是一个简单的错误修复。它是一个补丁,介绍Django功能,并做出一些设计决定。

如果您提供了一个非平凡的补丁,包括证据表明替代方案已在 django-developers 讨论。

如果你不确定你的补丁应该被认为是不平凡的,只是问。

弃用特征

Django中的代码可能已被弃用,这有几个原因:

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

  • 有时候,Django会包含一个Python库的后台,这个库不包含在Django目前支持的Python版本中。当Django不再需要支持不包括库的旧版本的Python时,该库将在Django中被弃用。

正如 deprecation policy 描述的,当调用过时的特性时,弃用特性(A.B)的第一个版本的Django应该引发 RemovedInDjangoXXWarning (其中XX是将删除特性的Django版本)。假设我们有良好的测试覆盖率,当启用警告的 运行测试套件python -Wall 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):
        ...
    

您还可以为弃用警告添加测试。你必须在测试中禁用“警告为错误”行为:

import warnings

def test_foo_deprecation_warning(self):
    with warnings.catch_warnings(record=True) as warns:
        warnings.simplefilter('always')  # prevent warnings from appearing as errors
        # invoke deprecated behavior

    self.assertEqual(len(warns), 1)
    msg = str(warns[0].message)
    self.assertEqual(msg, 'Expected deprecation message')

最后,Django的文档有一些更新:

  1. 如果现有功能已记录,请在文档中使用 .. deprecated:: A.B 注释标记为已弃用。包括简短描述和有关升级路径的注释(如果适用)。

  2. 在“AB中已弃用的功能”标题下,将已弃用的行为和升级路径(如果适用)的描述添加到当前版本说明(docs/releases/A.B.txt)中。

  3. 在弃用时间表(docs/internals/deprecation.txt)中的相应版本下添加一个条目,描述要删除的代码。

完成这些步骤后,即可完成折旧。在每个 feature release 中,删除与新版本匹配的所有 RemovedInDjangoXXWarning

JavaScript补丁

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

补丁审查清单

使用此清单查看提出请求。如果您正在查看不是您自己的拉取请求,并且通过了以下所有条件,请将相应Trac工单上的“分类阶段”设置为“准备签入”。如果您针对拉取请求留下了改进意见,请根据您的审核结果:“补丁需求改进”,“需要文档”和/或“需要测试”勾选Trac故障单上的相应标记。随着时间和兴趣许可,核心开发人员对“准备签入”票据进行最终审查,如果需要进一步工作,则将提交补丁或将其重新“接受”。如果你想成为一个核心开发人员,对补丁进行彻底的审查是一个伟大的方式来获得信任。

要查找补丁以进行审核?查看 Django开发仪表板 的“需要审核的补丁”部分。寻找补丁审查?确保已设置故障单上的Trac标志,以使故障单显示在该队列中。

文档

  • 文档是否构建没有任何错误(make htmlmake.bat html 在Windows上,从 docs 目录)?

  • 文档是否遵循 编写文档 中的写作风格指南?

  • 有没有任何 拼写错误

虫子

  • 是否有适当的回归测试(在应用修复之前测试应该失败)?

新功能

  • 有没有测试来“执行”所有的新代码?

  • docs/releases/A.B.txt 中有发布说明吗?

  • 是否有该功能的文档,它是与 .. versionadded:: A.B.. versionchanged:: A.B注释适当

弃用特征

请参阅 弃用特征 指南。

所有代码更改

  • 编码风格 是否符合我们的指南?是否有任何 flake8 错误?

  • 如果更改以任何方式向后不兼容,发行说明(docs/releases/A.B.txt)中是否有注释?

  • Django的测试套件是否通过?请在 #django-dev 中找到一个核心开发者来针对我们的持续集成服务器构建pull请求。

所有票