Submitting patches

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

Typo fixes and trivial documentation changes

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

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

“Claiming” tickets

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

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

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

  • 使用您的GitHub帐户登录在我们的票证系统中创建一个帐户 如果您有帐户但忘记了密码,可以使用密码重置页重置密码。
  • 如果此问题的凭单尚不存在,请在我们的问题跟踪器中创建一个。
  • 如果此问题的故障单已存在,请确保没有人声明。 为此,请查看故障单的“所有者”部分。 如果它被分配给“nobody”,那么它可以声明。 否则,其他人也许会在这张票上工作。 或者发现另一个错误/功能进行工作,或联系在票上的开发人员提供帮助。 如果一张票已被分配了几个星期或几个月没有任何活动,可能是安全的重新分配给自己。
  • 登录您的帐户,如果还没有,请点击机票页面左上方的“GitHub登录”或“DjangoProject登录”。
  • 通过点击页面底部“操作”下方的“分配给自己”单选按钮,然后点击“提交更改”来声明该机票。

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

Ticket claimers’ responsibility

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

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

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

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

Which tickets should be claimed?

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

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

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

Patch style

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

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

当您认为您的工作已准备好审核后,请发送a GitHub pull request 请先使用我们的patch review checklist自行查看修补程序。

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

  • 按照git diff命令返回的格式提交修补程序。
  • 使用“附加文件”按钮将补丁附加到ticket tracker中的票证。 不要将补丁放在票证描述或注释中,除非它是单行补丁。
  • 使用.diff扩展名命名补丁文件;这将使票据跟踪器应用正确的语法高亮,这是非常有用的。

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

  • 确保您的代码符合我们的patch review checklist中的要求。
  • 检查机票上的“有补丁”框,并确保不需要检查“需要文档”,“需要测试”和“补丁需要改进”框。 这使得票据出现在开发仪表板上的“需要查看的补丁”队列中。

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):
        ...
    

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

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. 在相应的版本下添加删除时间轴(docs/internals/deprecation.txt)中的条目,描述将删除哪些代码。

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

JavaScript patches

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

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 要么 .. versionchanged :: A·B?

Deprecating a feature

请参阅Deprecating a feature指南。

All code changes

  • coding style是否符合我们的指南? 是否有任何flake8错误?
  • 如果更改以任何方式向后不兼容,发布说明(docs/releases/A.B.txt)中是否有注释?
  • Django的测试套件传递?

All tickets

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