我们总是感谢Django代码的补丁。确实,具有相关补丁的错误报告将比没有补丁的错误报告 更 快地得到修复。
如果您正在修复一个非常微不足道的问题,例如更改文档中的一个单词,推荐的方法是使用 GitHub 提交拉取请求,而无需使用 Trac 工单。
有关如何使用拉取请求的更多详细信息,请参见:doc:working-with-git
在一个全球有数百个贡献者的开源项目中,有效地管理沟通以避免重复工作并尽可能提高贡献者的效率是非常重要的。
因此,我们的政策是供贡献者“发布”工单,以便让其他开发人员知道正在处理特定的错误或功能。
如果您确定了要做出的贡献并且有能力解决(通过编程能力,Django内核知识水平和时间可用性来衡量),请按照以下步骤进行发表:
备注
Django软件基金会要求对Django贡献不小的补丁的人签署并提交 Contributor License Agreement 贡献者许可协议,以确保Django软件基金会对所有贡献都拥有明确的许可,从而为所有用户提供明确的许可。
发布工单后,您有责任以合理及时的方式处理该工单。 如果您没有时间来处理它,请先取消发布或不发布它!
如果一两周内没有任何关于特定已发布工单的进展迹象,则另一位开发人员可能会要求您放弃该发布了的工单,以使其不再被垄断,而其他人也可以发布。
如果您已发布工单,并且要花很长时间(几天或几周)编写代码,请通过在工单上发布评论来使每个人都保持最新状态。如果您不提供定期更新,并且不响应进度报告的请求,则您对工单的要求可能会被撤消。
与往常一样,多交流好过少交流!
在某些情况下,执行认领工单的步骤可能过于繁琐。
对于一些小的改动,比如文档中的错别字或只需要几分钟修复的小错误,您无需进行认领工单的繁琐步骤。直接提交您的补丁即可完成!
如果您已经准备好补丁,始终 可以向工单提交补丁,无论是否有其他人已经认领了该工单。
确保您所做的任何贡献至少满足以下要求:
当您认为您的工作已经准备好进行审查时,请发送 GitHub 拉取请求。请首先使用我们的 补丁审查清单 自行审查补丁。
如果由于某种原因无法发送拉取请求,您还可以在 Trac 中使用补丁。在使用这种方式时,请遵循以下准则。
git diff
命令返回的格式提交补丁。.diff
命名补丁文件; 这将使工单跟踪系统应用正确的语法突出显示,这非常有帮助。无论您以何种方式提交工作成果,请按照以下步骤操作。
一个“非微小”的补丁是指不仅仅是修复小错误的补丁。它是一个引入 Django 功能并做出某种设计决策的补丁。
如果您提供了一个复杂的补丁,请包含证据表明曾在 Django 论坛 或 django-developers 列表上讨论过替代方案。
如果你不确定你的补丁是否应该被认为是非微小的,请在票务系统上征求意见。
Django 中的代码可能被弃用的原因有几个:
正如 弃用政策 所描述的那样,第一个弃用某项功能的 Django 版本(A.B
)在调用被弃用功能时应该引发一个 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
...
重要的是在没有警告引用但在弃用结束时需要更改或删除的代码上方包含一个 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 的文档:
.. deprecated:: A.B
注解在文档中标记它为已弃用。如果适用,包括一个简短的描述和有关升级路径的说明。docs/releases/A.B.txt
)中,放在 "Features deprecated in A.B" 标题下。docs/internals/deprecation.txt
)中,描述将要被移除的代码。一旦完成了这些步骤,你就完成了弃用过程。在每个 特性发布 中,与新版本匹配的所有 RemovedInDjangoXXWarning
都会被移除。
有关 JavaScript 补丁的信息,请参阅 JavaScript 补丁 文档。
使用此清单来审查拉取请求。如果您正在审查一个不是您自己的拉取请求,并且它满足下面的所有标准,请将相应的 Trac 工单上的 "Triage Stage" 设置为 "Ready for checkin"。如果您已经在拉取请求上留下了改进的评论,请根据您的审查结果在 Trac 工单上选择适当的标志:"Patch needs improvement"、"Needs documentation" 和/或 "Needs tests"。根据时间和兴趣,合并者会对 "Ready for checkin" 的工单进行最终审查,并将补丁提交或将其推回 "Accepted",如果需要进一步的工作。如果您想成为合并者,认真审查补丁是赢得信任的好方法。
寻找需要审查的补丁吗?请查看 Django 开发仪表板 中的 "Patches needing review" 部分。希望您的补丁得到审查吗?请确保工单上的 Trac 标志已设置,以便工单出现在该队列中。
docs/releases/A.B.C.txt
中有一份发行说明?只会应用到主分支的 bug 修复不需要发行说明。docs/releases/A.B.txt
中有一份发行说明?.. versionadded:: A.B
或 .. versionchanged:: A.B
进行了注释?black
、blacken-docs
、flake8
或 isort
错误?您可以安装 pre-commit 钩子来自动捕获这些错误。docs/releases/A.B.txt
)中有说明?12月 04, 2023