正在提交修补程序

我们总是很感激Django代码的补丁。实际上,带有相关补丁的bug报告将得到修复。 far 比没有补丁的更快。

打字错误和琐碎的文档更改

如果您正在修复一个非常小的问题,例如更改文档中的一个单词,提供补丁的首选方法是使用不带trac票据的github pull请求。

使用Git和Github 有关如何使用拉请求的详细信息。

“申领”票

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

因此,我们的策略是为“索赔”票据的贡献者提供服务,以便让其他开发人员知道正在处理某个特定的bug或特性。

如果您已经确定了您想要做出的贡献,并且能够修复它(根据您的编码能力、Django内部知识和时间可用性来衡量),请按照以下步骤进行声明:

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

  • 如果此问题的通知单尚不存在,请在我们的 ticket tracker .

  • 如果此问题的票已经存在,请确保没有其他人认领它。要执行此操作,请查看票据的“所有者”部分。如果它被分配给“无人”,那么它就可以被索赔。否则,其他人可能正在处理这张票。或者找到另一个要处理的bug/特性,或者联系处理票据的开发人员以提供帮助。如果一张票被分配了几个星期或几个月没有任何活动,那么重新分配给自己可能是安全的。

  • 如果您还没有登录到您的帐户,请单击票据页面左上角的“Github登录”或“DjangOproject登录”。

  • 通过单击页面底部“操作”下的“分配给我自己”单选按钮申领票据,然后单击“提交更改”。

备注

Django软件基金会要求任何人贡献比微不足道的补丁到Django签名并提交一个 Contributor License Agreement 这确保Django软件基金会对所有捐款都有明确的许可,允许所有用户获得清晰的许可证。

检票人的责任

一旦你认领了一张票,你就有责任以一种合理及时的方式处理这张票。如果你没有时间来处理它,要么不理睬它,要么一开始就不认领它!

如果在一两周内某个特定的已申领车票没有进展的迹象,另一个开发商可能会要求您放弃该车票申领,这样它就不再被垄断,其他人也可以申领。

如果您已经申领了一张票,并且要花很长时间(几天或几周)来编码,那么通过在票上发表评论来保持每个人的更新。如果您没有提供定期更新,并且没有对进度报告的请求作出响应,那么您在通知单上的索赔可能会被撤销。

像往常一样,多沟通总比少沟通好!

应该申领哪些票?

在某些情况下,通过申请门票的步骤是过火的。

对于一些小的更改,例如文档中的错误或只需几分钟就可以修复的小错误,您不需要跳过索票的麻烦。直接提交你的补丁,你就完成了!

它是 总是 可以接受,不管是否有人声明,如果您碰巧有一个补丁准备好了,就向一个票据提交补丁。

补丁样式

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

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

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

当你认为你的工作已经准备好接受审查时,发送 a GitHub pull request . 请使用我们的 patch review checklist 第一。

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

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

  • 将修补程序附加到 ticket tracker ,使用“附加文件”按钮。拜托 不要 将补丁放在票据描述或注释中,除非它是单行补丁。

  • 将补丁文件命名为 .diff 扩展;这将使跟踪程序应用正确的语法突出显示,这非常有用。

无论您提交工作的方式如何,请遵循以下步骤。

  • 确保您的代码满足 patch review checklist .

  • 选中票据上的“has patch”(有补丁)框,确保未选中“needs documentation”(需要文档)、“needs tests”(需要测试)和“patch needs improvement”(补丁需要改进)框。这使票据显示在 Development dashboard .

非平凡补丁

一个“重要的”补丁不仅仅是一个小的bug修复。它是一个引入Django功能并做出某种设计决策的补丁。

如果您提供了一个重要的补丁程序,请提供在上讨论过替代方案的证据 Django Forum 或|Django-Developers|列表。

如果你不确定你的补丁是否应该被认为是非琐碎的,可以在罚单上征求意见。

贬低功能

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

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

  • 有时django会包含一个python库的后端口,该库不包含在django当前支持的python版本中。当Django不再需要支持不包含库的旧版本的python时,该库将在Django中被弃用。

作为 deprecation policy 描述了Django的第一个版本,它否决了一个功能 (A.B )应该提高 RemovedInDjangoXXWarning (其中xx是将删除该功能的django版本)调用不推荐使用的功能时。假设我们有良好的测试覆盖率,当 running the test suite 启用警告时: python -Wa runtests.py . 因此,在添加 RemovedInDjangoXXWarning 您需要消除或消除运行测试时生成的任何警告。

第一步是删除Django本身对弃用行为的任何使用。接下来,您可以使用 ignore_warnings decorator,在测试或类级别:

  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):
        # invoke deprecated behavior
        ...

重要的是要包括一个 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,
    )
    old_private_helper()
    ...

最后,要对Django的文档进行以下几项更新:

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

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

  3. 在折旧时间表中添加条目 (docs/internals/deprecation.txt )在描述将删除哪些代码的适当版本下。

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

javascript补丁

有关javascript修补程序的信息,请参阅 javascript补丁 文档。

补丁审查清单

使用此核对表可以查看拉式请求。如果您正在审查非您自己的Pull请求,并且它通过了下面的所有标准,请将相应Trac票证上的“Triage Stage”设置为“Ready for Check”。如果您对Pull请求留下了改进意见,请根据您的审查结果在Trac工单上勾选相应的标志:“补丁需要改进”、“需要文档”和/或“需要测试”。在时间和兴趣允许的情况下,合并公司将对“准备好签入”的票据进行最终审查,如果需要进一步的工作,将提交补丁或将其恢复为“已接受”。如果你正在寻求合并,对补丁进行彻底的审查是赢得信任的好方法。

正在查找要审阅的修补程序?查看 Django Development Dashboard . 想要检查你的补丁吗?确保已设置票据上的TRAC标志,以便票据显示在该队列中。

文档

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

  • 文档是否遵循 编写文档 是吗?

  • 有没有 spelling errors 是吗?

漏洞

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

  • 如果这是一个错误 qualifies for a backport 对于稳定版本的Django,有没有发布说明 docs/releases/A.B.C.txt ?只应用于主分支的错误修复不需要发布说明。

新特点

  • 是否有测试来“练习”所有新代码?

  • 里面有发行说明吗 docs/releases/A.B.txt 是吗?

  • 这个功能有文档吗? annotated appropriately 具有 .. versionadded:: A.B.. versionchanged:: A.B 是吗?

贬低功能

贬低功能 指南。

所有代码更改

  • 这是不是 coding style 是否符合我们的指导方针?有没有 blackblacken-docsflake8 ,或 isort 错误?您可以安装 pre-commit 用于自动捕获这些错误的挂钩。

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

  • Django的测试套件通过了吗?

所有票