我们总是感谢Django的代码补丁。 事实上,具有相关补丁的错误报告将比没有补丁的错误报告更快地固定在远。
如果你正在修复一个非常微不足道的问题,例如更改文档中的一个词,提供补丁的首选方式是使用GitHub pull请求,而没有Trac票。
有关如何使用pull请求的更多详细信息,请参阅Working with Git and GitHub。
在一个开源项目中,世界各地有数百个贡献者,重要的是有效地管理通信,使工作不会重复,贡献者可以尽可能有效。
因此,我们的政策是为贡献者“声明”门票,以便让其他开发人员知道正在处理特定的错误或功能。
如果你确定了一个你想要的贡献,你有能力修复它(根据你的编码能力,Django内部和时间可用性的知识衡量),通过以下步骤声明:
注
Django软件基金会要求任何人贡献超过一个小的补丁Django签名并提交贡献者许可协议,这确保Django软件基金会有明确的许可证所有捐款允许一个明确的许可证所有用户。
一旦您申领了机票,您有责任以合理及时的方式处理该机票。 如果你没有时间去工作,可以取消声明它,或者不首先声明它!
如果在一周或两周的特定索赔机票上没有进展迹象,另一个开发商可能会要求您放弃机票索赔,使其不再被垄断,其他人可以索取。
如果您已经声明了一张机票,并且代码需要很长时间(几天或几周),请通过在机票上发布评论来更新每个人。 如果您不提供定期更新,并且您没有回应进度报告的请求,您对该机票的索赔可能会被撤销。
和往常一样,更多的沟通比更少的沟通更好!
当然,在某些情况下,通过申请车票的步骤是过度的。
在小的变化的情况下,如文档中的拼写错误或小错误,只需要几分钟的时间来修复,你不需要跳过申领机票的圈子。 只需提交您的补丁并完成它。
当然,无论是否有人声称它,始终都可以接受,如果您碰巧有补丁就绪,可以向故障单提交补丁。
确保您所做的任何贡献至少满足以下要求:
当您认为您的工作已准备好审核后,请发送a GitHub pull request。 请先使用我们的patch review checklist自行查看修补程序。
如果由于某种原因您无法发送拉请求,还可以在Trac中使用补丁。 使用此样式时,请遵循以下准则。
git diff
命令返回的格式提交修补程序。.diff
扩展名命名补丁文件;这将使票据跟踪器应用正确的语法高亮,这是非常有用的。无论您提交作品的方式如何,请按照下列步骤操作。
一个“不平凡”的补丁是一个不只是一个简单的错误修复。 这是一个补丁,介绍Django功能,并做出一些设计决定。
如果您提供了一个非平凡的补丁,请包括在django-developers上讨论替代方法的证据。
如果你不确定你的补丁应该被认为是不平凡的,只是问。
有几个原因,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
装饰器,在实际测试已弃用的行为的测试中静默警告:
在特定测试中:
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):
...
您还可以为弃用警告添加测试。 您必须通过执行以下操作来禁用测试中的“警告为错误”行为:
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的文档有一些更新:
.. 弃用:: A·B
注解。 包括简短描述和有关升级路径的注释(如果适用)。docs/releases/A.B.txt
)中添加已弃用的行为和升级路径(如果适用)的描述。docs/internals/deprecation.txt
)中的条目,描述将删除哪些代码。完成这些步骤后,即可完成弃用操作。
在每个feature release中,删除与新版本匹配的所有RemovedInDjangoXXWarning
。
有关JavaScript补丁的信息,请参阅JavaScript patches文档。
使用此清单查看提出请求。 如果您正在查看不是您自己的拉取请求,并且通过了以下所有条件,请将相应Trac工单上的“分类阶段”设置为“准备签入”。 如果您针对拉取请求留下了改进意见,请根据您的审核结果:“补丁需求改进”,“需要文档”和/或“需要测试”勾选Trac故障单上的相应标记。 随着时间和兴趣许可,提交者对“准备签到”门票进行最终审查,如果需要进一步的工作,将会将修补程序提交或者将其复制回“接受”。 如果你想成为一个提交者,对补丁进行彻底的评论是获得信任的好方法。
要查找补丁以进行审核? 请查看Django开发信息中心的“需要审核的补丁”部分。 寻找补丁审查? 确保已设置故障单上的Trac标志,以便故障单显示在该队列中。
make html
或make.bat html
在Windows上,从docs
目录)?docs/releases/A.B.txt
中是否有发布说明?.. versionadded :: A·B
要么 .. versionchanged :: A·B
?请参阅Deprecating a feature指南。
flake8
错误?docs/releases/A.B.txt
)中是否有注释?AUTHORS
文件,并提交贡献者许可协议。2017年9月6日