Skip to main content

检票

Django使用 Trac 来管理代码库上的工作。 Trac是一个社区倾向的花园的人们发现的错误和人们想看到添加的功能。在任何花园里,有时有杂草被拉,有时有花和蔬菜需要采摘。我们需要你的帮助来整理一个,而最终我们都能共同受益。

像所有的花园,我们可以追求完美,但在现实中没有这样的事情。即使在最原始的花园里仍然有蜗牛和昆虫。在社区花园里也有帮助的人谁 - 用最好的意图 - 施肥的杂草和毒玫瑰。社区整体的工作是自我管理,将问题降至最低,教育那些进入社区的人,使他们成为有价值的贡献成员。

同样,虽然我们的目标是让Trac成为Django进步状态的完美表示,但我们承认这根本不会发生。通过将Trac维护的负载分配给社区,我们接受会出现错误。 Trac是“最准确的”,我们给予的事实,有时它会是错误的允许。没关系。我们是最后期限的完美主义者。

我们依靠社区继续参与,保持门票尽可能准确,并提出问题,在我们的邮件列表讨论,当有混乱或不同意。

Django是一个社区项目,每一个贡献都有帮助。我们不能没有 这样做!

分类工作流

不幸的是,并非所有的错误报告和功能请求在机票跟踪器提供所有的 required details。许多票有补丁,但是这些补丁不满足 good patch 的所有要求。

帮助的一种方法是由其他用户创建的 triage 票证。核心团队和几个社区成员定期工作,但更多的帮助总是感谢。

大多数工作流程基于票证的 分类阶段 的概念。每个阶段描述在其生命中在任何时间给定票据的位置。除了少量的标志,这个属性很容易告诉我们什么和每张票是什么等待。

因为一张图片值得一千字,让我们从那里开始:

Django's ticket triage workflow

我们在这个图中有两个角色:

  • 提交者(也称为核心开发者):具有提交权限的人员,负责作出决策和整合社区的贡献。

  • Ticket triagers:Django社区的任何人选择参与Django的开发过程。我们的Trac安装有意向公众开放,任何人都可以检票。 Django是一个社区项目,我们鼓励 triage by the community

举例来说,这里我们看到平均票的生命周期:

  • Alice创建一个票证,并上传一个不完整的补丁(没有测试,不正确的实现)。

  • 鲍勃审查补丁,标记为“接受”,“需要测试”和“补丁需求改进”,并留下一个评论告诉爱丽丝如何可以改进补丁。

  • Alice更新补丁,添加测试(但不改变实现)。她删除了两个标志。

  • Charlie审查补丁,并重新设置“补丁需求改进”标志,另一个关于改进实现的注释。

  • Alice更新补丁,修复实现。她删除“补丁需求改进”标志。

  • Daisy审查补丁,并标记它RFC。

  • Jacob,一个核心开发人员,审查RFC补丁,应用到他的结账,并提交它。

有些票需要比这少得多的反馈,但后来一些票需要更多。

分类阶段

下面我们更详细地描述票在其寿命期间可能流过的各个阶段。

未审查

票据没有被任何人审查,任何人谁有资格做出判断,票是否包含有效的问题,一个可行的功能,或应该由于各种原因关闭。

公认

大灰色地带! “接受”的绝对含义是,票证中描述的问题是有效的,并且处于某些正在处理的阶段。除此之外,还有几个注意事项:

  • 接受+无标志

    票是有效的,但还没有人提交补丁。通常这意味着你可以安全地开始为它写一个补丁。这对于接受的错误的情况通常比接受的特征更真实。已经被接受的错误的票证意味着该问题已经被至少一个triger验证为合法的错误 - 并且如果可能的话应该是固定的。接受的新特征可能仅意味着一个三元组认为该特征将是好的,但是这本身并不代表一致的观点或意味着任何确定性将接受该特征的补丁。如果您有疑问,请在编写大量补丁之前获得更多反馈。

  • 接受+有补丁

    该票正在等待人们查看提供的修补程序。这意味着下载补丁并试用它,验证它包含测试和文档,运行包含补丁的测试套件,并在故障单上留下反馈。

  • 接受+有补丁+需要...

    这意味着票已经过审查,并且已被发现需要进一步的工作。 “需要测试”和“需要文档”是不言自明的。 “补丁需求改进”通常伴有对票证的解释,说明需要改进代码。

准备好入住

除了提供补丁并发现满足提交就绪补丁的所有要求的人之外,任何社区成员都审查了该票。提交者现在需要在提交之前给补丁一个最终审查。看到 New contributors’ FAQ “我的票已经在RFC永远!我该怎么办?

有一天/可能

此阶段未在图中显示。它只被核心开发人员用来跟踪高级想法或长期功能请求。

这些票是不常见的,总体上不太有用,因为它们没有描述具体的可操作的问题。它们是增强请求,如果提交了优秀的补丁,我们可能会考虑向框架中添加一天。它们不是高优先级。

其他分类属性

在票证中可以设置多个在Trac中显示为复选框的标志:

有补丁

这意味着票证具有关联的 patch。这些将被审查,看看补丁是否“好”。

以下三个字段(需要文档,需要测试,补丁需求改进)仅适用于已提供补丁的情况。

需要文档

此标志用于包含需要关联文档的修补程序的故障单。功能的完整文档是一个先决条件,然后我们才能将其检入代码库。

需要测试

这标志着补丁需要相关的单元测试。同样,这是有效补丁的必需部分。

补丁需求改进

这个标志意味着虽然票 has 是一个补丁,它还没有准备好签到。这可能意味着补丁不再适用干净,在实施中有缺陷,或者代码不符合我们的标准。

轻松选择

门票,需要小,容易,补丁。

类型

门票应由 type 分类为:

  • 新功能

    添加新的东西。

  • 错误

    当一个现有的东西被破坏或不按预期行事时。

  • 清理/优化

    当没有什么破碎,但东西可以做得更干净,更好,更快,更强。

零件

门票应该被分类为 components,指示它们属于哪个区域的Django代码库。这使得票更好的组织和更容易找到。

严重性

severity 属性用于标识阻止程序,即在发布下一个版本的Django之前应该解决的问题。通常这些问题是导致来自早期版本的回退的错误或潜在地导致严重的数据丢失。此属性很少使用,绝大多数票证的严重性为“正常”。

可以使用 version 属性来指示在哪个版本中识别所报告的错误。

UI/UX

此标志用于与用户界面和用户体验问题相关的票证。例如,此标志适用于表单中的面向用户的功能或管理界面。

Cc

您可以将此用户名或电子邮件地址添加到此字段,以便在对票证进行新捐款时收到通知。

关键词

使用此字段,您可以标记具有多个关键字的支持消息。这可以是有用的,例如,将同一主题的几张票分组。关键字可以是逗号或空格分隔。关键字搜索在关键字的任何位置找到关键字字符串。例如,单击具有关键字“form”的票证将产生用包含诸如“formset”,“modelformset”和“ManagementForm”的字符串的关键字标记的类似票券。

关闭票证

当票证已经完成其有用的生命周期时,它的时间是关闭。但是,关闭机票是一个重大的责任。你必须确保问题真的得到解决,你需要记住的是,机票的记者可能不高兴让他们的票关闭(除非它是固定的,当然)。如果你不确定要关闭机票,只需留下你的想法。

如果您关闭机票,您应该始终确保以下内容:

  • 确保问题得到解决。

  • 留下解释决定关闭机票的评论。

  • 如果有一种方法,他们可以改进票,重新打开它,让他们知道。

  • 如果故障单是重复的,请参考原始故障单。还通过在原始代码中留下评论来交叉引用已关闭的票据 - 这允许访问关于所报告的错误或所请求的特征的更多相关信息。

  • 要有礼貌。 没有人喜欢他们的票。它可能令人沮丧,甚至令人沮丧。避免让人们停止对Django的贡献的最好方法是礼貌和友好,并提供建议,如何可以改进这张票和其他票在将来。

票可以通过多种方式解决:

  • 固定

    一旦补丁已经被转换到Django并且问题是固定的,由核心开发人员使用。

  • 无效

    如果发现票证不正确,则使用。这意味着票证中的问题实际上是用户错误的结果,或描述了除Django之外的问题,或者根本不是错误报告或功能请求(例如,一些新用户提交支持查询门票)。

  • wontfix

    当核心开发人员决定此请求不适合在Django中考虑时使用。这通常是在 django-developers 邮件列表中讨论后选择的。随时开始或加入在 django-developers 邮件列表上的“wontfix”门票的讨论,但请不要重新打开由 core developer “wontfix”关闭的门票。

  • 重复

    当另一张票覆盖相同的问题时使用。通过关闭重复的票,我们把所有的讨论在一个地方,这有助于大家。

  • worksforme

    当票证不包含足够的详细信息以复制原始错误时使用。

  • 需求信息

    当故障单不包含足够的信息以复制报告的问题但可能仍然有效时使用。当提供更多信息时,应重新打开该票。

如果您认为该票错误地关闭了,因为您仍然遇到问题,或者其他地方弹出,或者三人组成了错误,请重新打开票证并提供进一步的信息。再次,请不要重新打开已被标记为“wontfix”的核心开发者的票,并将问题提交给 django-developers

我如何帮助分类?

分流过程主要由社区成员驱动。真的,任何人 可以帮助。

核心开发人员可以提供有关他们熟悉的问题的反馈,或对有争议的问题做出决定,但是他们不负责一般性的票务。

要参与,从 creating an account on Trac 开始。如果您有帐户,但忘记了密码,则可以使用 password reset page 重置密码。

然后,你可以帮助:

  • 关闭“未审核”票为“无效”,“工作正式”或“重复”。

  • 当描述过于稀疏,无法操作时,或者当需要对 django-developers 进行讨论的功能请求时,将“未查看”票单关闭为“needsinfo”。

  • 更正错误设置的故障单的“需要测试”,“需要文档”或“有补丁”标志。

  • 为小票和相对简单的票设置“ Easy pickings ”标志。

  • 设置尚未分类的票证的 type

  • 检查旧票证是否仍然有效。如果票证在很长时间内没有看到任何活动,则可能是问题已解决,但票证尚未关闭。

  • 识别门票中的趋势和主题。如果有很多关于Django的特定部分的错误报告,它可能表明我们应该考虑重构该部分代码。如果一个趋势出现,你应该提出来讨论(参考相关门票)在 django-developers

  • 验证其他用户提交的修补程序是否正确。如果它们是正确的,并且包含适当的文档和测试,则将其移动到“准备签入”阶段。如果他们不正确,那么留下评论来解释为什么,并设置相应的标志(“补丁需求改进”,“需要测试”等)。

注解

Reports page 包含许多有用的Trac查询的链接,包括几个如上所述的用于分类票证和审查补丁的有用的。

你也可以找到更多的 对新贡献者的建议

但是,我们要求在票证数据库中工作的所有一般社区成员:

  • 关闭机票作为“wontfix”。核心开发者将通过与社区磋商后对票据的命运做出最终决定。

  • 推广您自己的门票“准备签入”。您可以标记您已经审查为“准备签入”的其他人的机票,但您应该至少有一个其他社区成员审查您提交的修补程序。

  • 撤销 core developer 作出的决定。如果您不同意已作出的决定,请向 django-developers 发送消息。

  • 如果您不确定是否应该进行更改,请不要进行更改,而是对您的问题留下评论,或向 django-developers 发送消息。可以不确定,但你的输入仍然有价值。

平分回归

回归是一个错误,存在于一些较新的Django版本,但不是在较旧的。一个非常有用的信息是介绍回归的承诺。知道引起行为变化的提交有助于识别变化是有意的还是无意的副作用。这里是如何确定这一点。

首先为问题编写Django测试套件的回归测试。例如,我们假设我们正在调试迁移中的回归。在写完测试并确认其在最新主控上失败后,将其放在一个可以独立运行的单独文件中。对于我们的例子,我们假装我们创建了 tests/migrations/test_regression.py,它可以运行:

$ ./runtests.py migrations.test_regression

接下来,我们将历史中的当前点标记为“坏”,因为测试失败:

$ git bisect bad
You need to start by "git bisect start"
Do you want me to do it for you [Y/n]? y

现在,我们需要在引入回归之前在git历史中找到一个点(即测试通过的点)。使用类似 git checkout HEAD~100 来检出早期版本(在这种情况下,提前100个提交)。检查测试是否失败。如果是这样,将该点标记为“坏”(git bisect bad),然后检出早期版本并重新检查。一旦你找到你的测试通过的修订版,标记为“好”:

$ git bisect good
Bisecting: X revisions left to test after this (roughly Y steps)
...

现在我们准备好了有趣的部分:使用 git bisect run 自动化的剩余过程:

$ git bisect run tests/runtests.py migrations.test_regression

你应该看到 git bisect 使用二进制搜索来自动检查好和坏提交之间的修订,直到它找到测试失败的第一个“坏”提交。

现在,在Trac票上报告您的结果,并请将回归测试作为附件包括在内。当有人写一个bug的修复,他们已经有你的测试作为起点。