Submitting patches

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

Typo fixes and trivial documentation changes

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

有关如何使用pull请求的更多详细信息,请参阅Working with Git and GitHub

“Claiming” tickets

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

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

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

  • 创建帐户以在我们的票系统中使用。如果您有帐户但忘记了密码,可以使用密码重置页重置密码。
  • 如果此问题的凭单尚不存在,请在我们的问题跟踪器中创建一个。
  • 如果此问题的故障单已存在,请确保没有人声明。为此,请查看故障单的“所有者”部分。如果它被分配给“nobody”,那么它可以声明。否则,有人正在处理此故障单,您可能会找到另一个错误/功能来处理,或联系工作在故障单上的开发人员提供帮助。
  • 如果您还没有登录到您的帐户,请点击机票页面右上角的“登录”。
  • 索赔票:
    1. 单击页面底部附近“操作”下的“分配给我自己”单选按钮,
    2. 然后点击“提交更改”。

注意

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

Ticket claimers’ responsibility

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

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

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

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

Which tickets should be claimed?

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

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

当然,无论是否有人声称它,始终都可以接受,如果您碰巧有补丁就绪,可以向故障单提交补丁。

Patch style

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

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

您可以使用GitHub分支和拉取请求或直接补丁来发布您的工作。如果您使用Git工作流程,那么您应该通过包括指向您的分支的链接在故障单中宣布您的分支。当你认为你的工作准备好合并在创建一个pull请求。

有关更多详细信息,请参阅Working with Git and GitHub文档。

您还可以在Trac中使用修补程序。使用此样式时,请遵循以下准则。

  • 按照git diff命令返回的格式提交修补程序。一个例外是代码更改,更清楚地用简单的英语而不是代码。缩进是最常见的例子;它很难读补丁,当代码中的唯一区别是它缩进。
  • 使用“附加文件”按钮将补丁附加到ticket tracker中的票证。不要将补丁放在票证描述或注释中,除非它是单行补丁。
  • 使用.diff扩展名命名补丁文件;这将使票据跟踪器应用正确的语法高亮,这是非常有用的。

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

  • 请确保您的代码符合我们的Coding style
  • 检查票证详细信息上的“有补丁”框。这将使得票明显包括补丁,并且它将票添加到具有补丁的票的列表中。

Non-trivial patches

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

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

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

Deprecating a feature

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

  • 如果某个功能已经以向后不兼容的方式改进或修改,旧的功能或行为将被弃用。
  • 有时候,Django会包含一个Python库的后端,它不包含在Django目前支持的Python版本中。当Django不再需要支持不包括库的旧版本的Python时,该库将在Django中被弃用。

正如deprecation policy所述,第一个弃用功能(A.B)的Django版本应该会产生RemovedInDjangoXXWarning(其中XX是Django版本当删除特征时)。Assuming we have good test coverage, these warnings are converted to errors when running the test suite with warnings enabled: 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):
        ...
    
在Django 1.8中更改:

先前版本的Django有一些Ignore*DeprecationWarningsMixin类,以防止出现警告。这些已替换为ignore_warnings装饰器。

您还可以为弃用警告添加测试。您必须通过执行以下操作来禁用测试中的“警告为错误”行为:

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. 如果现有功能已记录,请在文档中使用.. 弃用的 A.B注释标记已弃用的功能。包括简短描述和有关升级路径的注释(如果适用)。
  2. 在“在A.B中弃用的功能”标题下的当前版本说明(docs/releases/A.B.txt)中添加已弃用的行为和升级路径(如果适用)的描述。
  3. A.B+2版本的弃用时间轴(docs/internals/deprecation.txt)中添加一个条目,描述要删除的代码。

完成这些步骤后,即可完成弃用操作。在每个主要版本中,将删除与新版本匹配的所有RemovedInDjangoXXWarning

JavaScript patches

Django的管理系统利用jQuery框架来增加管理界面的功能。结合,强调管理JavaScript性能和最小化整体管理媒体文件大小。在这方面,将JavaScript文件的压缩或“缩小”版本视为最佳做法。

为此,JavaScript文件的补丁应该包括用于未来开发的原始代码(例如,foo.js),以及用于生产使用的压缩版本(例如,foo.min.js)。到代码库中的文件的任何链接应指向压缩版本。

Compressing JavaScript

为了简化提供优化的JavaScript代码的过程,Django包括一个方便的python脚本,应该用来创建一个“minified”版本。运行它:

python django/contrib/admin/bin/compress.py

在幕后,compress.py是Google的Closure Compiler的前端,它是用Java编写的。但是,Closure Compiler库不直接与Django捆绑在一起,因此希望提供完整的JavaScript补丁的用户需要单独下载和安装该库。Closure编译器库需要Java 7或更高版本。

在为Django的JavaScript提交补丁时,请不要忘记运行compress.py并添加缩小脚本的diff

Patch review checklist

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

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

Documentation

  • 文档是否生成没有任何错误(make htmlmake.bat html 在Windows上,从docs目录)?
  • 文档是否遵循Writing documentation中的写作风格指南?
  • 是否有任何spelling errors

Bugs

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

New Features

  • 有没有测试来“运行”所有的新代码?
  • docs/releases/A.B.txt中是否有发布说明?
  • Is there documentation for the feature and is it annotated appropriately with .. versionadded:: A.B or .. versionchanged:: A.B?

Deprecating a feature

请参阅Deprecating a feature指南。

All code changes

  • coding style是否符合我们的指南?是否有任何flake8错误?
  • 如果更改以任何方式向后不兼容,发布说明(docs/releases/A.B.txt)中是否有注释?
  • Django的测试套件传递?#django-dev中请求核心开发人员针对我们的持续集成服务器构建pull请求。

All tickets

  • 是拉取请求一个单独的提交,并且跟随我们的commit message format的消息吗?
  • 你是补丁作者和一个新的贡献者吗?请将自己添加到AUTHORS文件,并提交贡献者许可协议