试用票

Django使用 Trac 用于管理代码库上的工作。Trac是一个社区管理的花园,里面有人们发现的错误和人们希望看到的添加的功能。就像在任何花园里一样,有时需要拔杂草,有时需要采摘鲜花和蔬菜。我们需要你的帮助来区分它们,最终,我们都会共同受益。

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

同样,虽然我们的目标是让Trac完美地代表Django的进展情况,但我们承认这不会发生。通过将Trac维护的负荷分配给社区,我们承认会出现错误。Trac“基本上是准确的”,我们考虑到有时它是错误的。没关系。我们是有期限的完美主义者。

我们依靠社区来保持参与,保持门票尽可能准确,并在出现混乱或分歧时在我们的邮件列表上提出讨论问题。

Django是一个社区项目,每一项贡献都是有帮助的。我们不能没有 you 你说什么?

分流工作流程

不幸的是,并非所有的bug报告和特性请求都提供了 required details . 很多票都有补丁,但这些补丁不能满足 good patch .

帮助的一个方法是 分诊 由其他用户创建的票据。

大多数工作流都是基于票据的概念 triage stages . 每个阶段描述在其生命周期中,给定的票据在任何时间的位置。除了一些标志之外,这个属性很容易告诉我们每一张票都在等待什么和谁。

既然一张图片值千言万语,我们就从这里开始:

Django的票证分类工作流

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

  • 合并者:具有提交访问权限的人员,负责做出合并补丁的最终决定。

  • 检票员:在Django社区中选择参与Django发展过程的任何人。我们的trac装置是故意向公众开放的,任何人都可以分类标签。Django是一个社区项目,我们鼓励 triage by the community .

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

  • Alice创建一个票据并发送一个不完整的请求(没有测试,实现不正确)。

  • Bob审查了Pull请求,将罚单标记为“已接受”、“需要测试”和“补丁需要改进”,并留下一条评论,告诉Alice如何改进补丁。

  • Alice更新pull请求,添加测试(但不更改实现)。她把两个旗子取下来。

  • charlie检查pull请求并重置“patch needs improvement”(补丁需要改进)标志,并给出另一条关于改进实现的注释。

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

  • Daisy检查了请求并将票据标记为“准备好签入”。

  • 雅各布,一个 merger 审阅拉入请求并将其合并。

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

分流期

下面我们将更详细地描述一张票在其生命周期中可能经历的各个阶段。

未审查的

任何认为有资格对该票是否包含有效问题、可行功能或因任何原因应关闭作出判断的人都没有审查该票。

认可的

大灰色区域!“接受”的绝对含义是,票据中描述的问题是有效的,并且处于正在进行的某个阶段。除此之外,还有几个考虑因素:

  • 接受+无标志

    该票有效,但还没有人为此提交补丁。这通常意味着您可以安全地开始为它编写补丁。对于接受的bug,这通常比接受的特性更为正确。一张已被接受的bug的罚单意味着该问题已被至少一个Triager验证为合法的bug,如果可能的话,该问题应该被修复。一个被接受的新特性可能只意味着一个验尸官认为该特性是好的,但这一点本身并不代表一种共识,也不意味着一个补丁将被该特性接受。如果您有疑问,请在编写大量补丁之前寻求更多反馈。

  • 接受+有补丁

    票据正在等待人们查看提供的补丁。这意味着下载补丁并尝试它,验证它是否包含测试和文档,使用包含的补丁运行测试套件,并在票据上留下反馈。

  • 接受+有补丁+需求…

    这意味着票已经过审核,并且发现需要进一步的工作。”“需求测试”和“需求文档”是不言而喻的。补丁需要改进”通常会在标签上附带一条注释,说明需要什么来改进代码。

准备好登记了

除了提供补丁程序的人之外,社区中的任何成员都会查看该票证,发现它满足提交就绪补丁程序的所有要求。一个 merger 现在需要在提交补丁之前对其进行最终审查。

有很多拉取请求。您的补丁可能需要一段时间才能得到审查。请参阅 contributing code FAQ 在这里寻找一些想法。

有一天

图中未显示此阶段。它很少被用来跟踪高级想法或长期的功能请求。

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

其他分类属性

可以在票据上设置多个标记(在TRAC中显示为复选框):

有补丁

这意味着票上有一个 patch . 这些将被审查,看看补丁是否“好”。

以下三个字段(需要文档、需要测试、补丁需要改进)仅在提供了补丁的情况下适用。

需要文档

此标志用于具有需要相关文档的修补程序的票据。在我们将特性检入代码库之前,完整的特性文档是一个先决条件。

需要测试

这会将补丁标记为需要关联的单元测试。同样,这是有效补丁的必需部分。

补丁需要改进

这个标志意味着尽管 has 一个补丁,还没准备好登记。这可能意味着补丁不再干净地应用,实现中存在缺陷,或者代码不符合我们的标准。

易拾取

需要小而简单的补丁的票。

类型

门票应按 type 之间:

  • 新特点

    为了增加新的东西。

  • 缺陷

    因为当一个现存的事物被破坏或没有如预期的那样行为。

  • 清理/优化

    因为当没有什么东西被打破,但一些东西可以变得更干净,更好,更快,更强。

成分

门票应分为 组件 指示它们属于Django代码库的哪个区域。这使得门票更有条理,更容易找到。

严重程度

这个 severity 属性用于标识拦截器,即在发布下一个版本的Django之前应该修复的问题。通常,这些问题是错误,会导致较早版本的倒退或可能导致严重的数据丢失。这个属性很少使用,并且绝大多数票证的严重性都是“正常”。

版本

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

用户界面/用户体验

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

复写的副本

您可以将您的用户名或电子邮件地址添加到此字段,以便在向票据作出新的贡献时得到通知。

关键词

使用此字段,您可以使用多个关键字标记一张票证。这可能非常有用,例如,对同一主题的多个票证进行分组。关键字可以用逗号或空格分隔。关键字搜索在关键字中的任何位置查找关键字字符串。例如,单击带有关键字“form”的票证将会出现类似的票证,这些票证带有关键字标记,这些关键字包含字符串,如“formset”、“Model formset”和“ManagementForm”。

结业券

当一个票证已经完成了它的有用生命周期,它是时候关闭它了。不过,关闭罚单是一个很大的责任。你必须确保这个问题真的得到了解决,而且你需要记住,罚单的报告者可能不乐意关闭他们的罚单(除非它被修复了!)。如果你不确定是否要关闭罚单,请留下你的想法。

如果您确实关闭了一张罚单,则应始终确保以下内容:

  • 确保问题得到解决。

  • 留下一条评论,解释关闭罚单的决定。

  • 如果有什么方法可以改进票据以重新打开它,请让他们知道。

  • 如果票据是副本,请参考原始票据。另外,通过在原始记录单中留下注释来交叉引用关闭的记录单——这允许访问关于报告的错误或请求的特性的更多相关信息。

  • 要有礼貌。 没有人喜欢把票关了。这可能令人沮丧,甚至令人沮丧。避免人们拒绝向 Django 捐款的最好方法是礼貌友好,并就如何改进这张票和今后的其他票提出建议。

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

  • 固定的

    在Django中滚动补丁并修复问题后使用。

  • 无效

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

  • 惯用固定

    当有人认为请求不适合在Django考虑时使用。有时,一张罚单会被关闭,并要求记者在网站上开始讨论 Django Forum 或者|Django-Developers|邮件列表,如果他们觉得与关闭罚单的人提供的理由不同。其他时候,在决定关闭门票之前会进行讨论。在重新开票之前,一定要在论坛或邮件列表上达成共识,然后才能重新开票。

  • 复制品

    当另一张票包含同一问题时使用。通过关闭重复的门票,我们将所有讨论放在一个地方,这对每个人都有帮助。

  • 工作形式

    当票据包含的细节不足以复制原始错误时使用。

  • 必需品

    当票证包含的信息不足,无法复制报告的问题,但可能仍然有效时使用。当提供更多信息时,应重新打开票据。

如果您认为票被错误地关闭了--因为您仍然有问题,或者它出现在其他地方,或者分拣人员犯了错误--请重新打开票并提供进一步的信息。再次声明,请不要重新打开已标记为“untfix”的票证,并将问题提交至 Django Forum 或者|Django-Developers|。

我如何帮助试诊?

分流过程主要由社区成员推动。真的? ANYONE 可以帮忙。

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

然后,您可以通过以下方式提供帮助:

  • 将“未查看”票据关闭为“无效”、“工作窗体”、“重复”或“Wontfix”。

  • 当描述太少而无法操作时,或者当它们是需要在上进行讨论的功能请求时,将“未审核”票据关闭为“nesisinfo” Django Forum 或|Django-Developers|。

  • 更正错误设置的票据的“需要测试”、“需要文档”或“有补丁”标志。

  • 为小票和相对简单的票设置“轻松挑选”标志。

  • 设置 type 未分类的票。

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

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

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

备注

这个 Reports page 包含指向许多有用的TRAC查询的链接,其中包括一些对于筛选票据和查看上面建议的补丁程序有用的链接。

你也可以找到更多 对新投稿人的建议 .

但是,我们确实要求在票务数据库中工作的所有普通社区成员:

  • don't 将您自己的机票宣传为“准备办理登机手续”。您可以将您已审阅的其他人的票证标记为“已准备好签入”,但您至少应该让其他社区成员审阅您提交的补丁。

  • don't 撤销决定,而不向 Django Forum 或者|Django-Developers|寻求共识。

  • 如果您不确定是否应该进行更改,请不要进行更改,而是在票证上留下您关心的问题的评论,或者向 Django Forum 或|Django-Developers|。不确定也没关系,但你的意见仍然很有价值。

平分回归

回归是一个bug,它存在于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编写修复程序时,他们已经将您的测试作为起点了。