分类票证 — Django 文档
分类工单
Django 使用 Trac 来管理代码库上的工作。 Trac 是一个社区照管的花园,其中包含人们发现的错误以及人们希望添加的功能。 就像在任何花园中一样,有时需要拔除杂草,有时需要采摘鲜花和蔬菜。 我们需要你的帮助,从中找出一个,最终我们都受益。
像所有花园一样,我们可以追求完美,但实际上没有这样的事情。 即使在最原始的花园里,仍然有蜗牛和昆虫。 在社区花园里,也有一些乐于助人的人——出于好意——给杂草施肥,给玫瑰施毒。 整个社区的工作是自我管理,将问题降到最低,并教育那些进入社区的人,使他们能够成为有价值的贡献成员。
同样,虽然我们的目标是让 Trac 成为 Django 进展状态的完美代表,但我们承认这根本不会发生。 通过将 Trac 维护的负载分配给社区,我们接受会出现错误。 Trac“基本准确”,我们承认有时它会出错。 没关系。 我们是有截止日期的完美主义者。
我们依靠社区继续参与,尽可能保持工单的准确性,并在出现困惑或分歧时在我们的邮件列表中提出问题供讨论。
Django 是一个社区项目,每一个贡献都有帮助。 没有你,我们做不到!
分诊工作流
不幸的是,并非票务跟踪器中的所有错误报告和功能请求都提供所有 所需的详细信息 。 许多票证都有补丁,但这些补丁不满足 好补丁 的所有要求。
提供帮助的一种方法是 triage 其他用户创建的票证。
大多数工作流程都基于工单的 分类阶段 的概念。 每个阶段都描述了给定票证在其生命周期中的任何时间。 连同一些标志,这个属性很容易告诉我们每张票在等待什么和谁。
既然一张图片值一千字,让我们从这里开始:
[[Django/docs/2.2.x/_images/triage_process|[[File:../../_images/triage_process.svg|400x501px|Django's ticket triage workflow]]]] 我们在这个图中有两个角色:
- 提交者:具有提交访问权限的人,负责做出合并补丁的最终决定。
- 票务分类员:Django 社区中选择参与 Django 开发过程的任何人。 我们的 Trac 装置特意向公众开放,任何人都可以对门票进行分类。 Django 是一个社区项目,我们鼓励社区 进行 分类。
举个例子,我们可以看到一张普通工单的生命周期:
- Alice创建一个工单并发送一个不完整的请求(没有测试,实现也不正确)。
- Bob 审查拉取请求,将故障单标记为“已接受”、“需要测试”和“补丁需要改进”,并留下评论告诉 Alice 如何改进补丁。
- Alice 更新拉取请求,添加测试(但不更改实现)。 她移除了两个标志。
- Charlie 审查拉取请求,并用另一条关于改进实现的评论重置“补丁需要改进”标志。
- Alice 更新拉取请求,修复实现。 她删除了“补丁需要改进”标志。
- Daisy 审查拉取请求并将票标记为“准备签入”。
- Jacob,一个提交者,检查pull请求并合并它。
有些工单需要的反馈比这少得多,但同样有些工单需要更多的反馈。
分类阶段
下面我们将更详细地描述工单在其生命周期中可能经历的各个阶段。
没有审阅
没有任何人对工单是否包含有效问题、可行功能或是否应因任何原因关闭而对工单进行审阅。
已接受
大灰色地带! “已接受”的绝对含义是票证中描述的问题是有效的,并且正在处理中。 除此之外还有几个考虑:
接受 + 无标志
票是有效的,但还没有人为它提交补丁。 通常这意味着您可以安全地开始为它编写补丁。 对于已接受的错误,这通常比已接受的功能更真实。 已接受错误的票证意味着该问题已被至少一个分类人员验证为合法错误 - 如果可能,应该予以修复。 一个被接受的新功能可能只意味着一个分类员认为该功能会很好,但这本身并不代表共识观点或暗示该功能的补丁将被接受的任何确定性。 如果您有疑问,请在编写大量补丁之前寻求更多反馈。
接受 + 有补丁
票正在等待人们查看提供的补丁。 这意味着下载补丁并试用它,验证它是否包含测试和文档,使用包含的补丁运行测试套件,并在票证上留下反馈。
接受 + 有补丁 + 需要……
这意味着该故障单已经过审核,并且发现需要进一步处理。 “需求测试”和“需求文档”是不言自明的。 “补丁需要改进”通常会在故障单上附上注释,说明需要改进代码的内容。
准备收入
票证由除提供补丁的人以外的任何社区成员进行审查,并发现满足提交就绪补丁的所有要求。 提交者现在需要在提交之前对补丁进行最终审查。 请参阅 新贡献者常见问题解答 中的“我的票永远在 RFC 中! 我该怎么办?”
几天/可能
此阶段未显示在图表中。 它很少用于跟踪高级想法或长期功能请求。
这些票并不常见,而且总体上不太有用,因为它们没有描述具体的可操作问题。 如果提交了出色的补丁,我们可能会考虑将它们添加到框架中。 它们不是高优先级。
其他分类属性
可以在工单上设置许多标志,这些标志在Trac中显示为复选框:
需要文档
此标志用于带有需要相关文档的补丁的票证。 完整的功能文档是我们将它们签入代码库之前的先决条件。
需要测试
这将补丁标记为需要关联的单元测试。 同样,这是有效补丁的必需部分。
补丁需要改进
这个标志意味着虽然票证 有 一个补丁,但它还没有准备好签入。 这可能意味着补丁不再适用,实现中存在缺陷,或者代码不符合我们的标准。
容易挑选
需要小的,容易的补丁的工单。
类型
机票应按 类型 分类:
- *; 新特性
- 为了添加一些新东西。
- *; 错误
- 指☞一些损坏的或者行为与预期不符的地方。
- *; 清理/优化
- 指那些没有东西被破坏,同时有一些东西可以变得更干净、更好、更快、更强的地方。
组件
票证应分类为 components,表明它们属于 Django 代码库的哪个区域。 这使得门票更有条理,更容易找到。
严重性
severity 属性用于识别拦截器,即在发布下一个 Django 版本之前应该修复的问题。 通常,这些问题是导致早期版本回归或可能导致严重数据丢失的错误。 此属性很少使用,绝大多数故障单的严重性为“正常”。
版本
可以使用 version 属性来指示报告的错误是在哪个版本中识别的。
UI/UX
此标志用于与用户界面和用户体验问题相关的票证。 例如,此标志适用于表单或管理界面中面向用户的功能。
副本
您可以将您的用户名或电子邮件地址添加到该字段,以便在对工单进行新的投稿时收到通知。
关键词
使用此字段,您可以使用多个关键字标记工单。 例如,这对于将同一主题的多张票进行分组很有用。 关键字可以用逗号或空格分隔。 关键字搜索在关键字中的任何位置查找关键字字符串。 例如,单击带有关键字“form”的工单将产生类似的工单,这些工单带有包含“formset”、“modelformset”和“ManagementForm”等字符串的关键字。
关闭工单
当票证完成其有用的生命周期后,就该关闭它了。 但是,关闭票证是一项重大责任。 您必须确保问题确实得到了解决,并且您需要记住,票证的报告者可能不乐意关闭他们的票证(当然,除非它已修复)。 如果您不确定是否关闭工单,只需发表您的想法即可。
如果您确实关闭了工单,则应始终确保以下事项:
- 确认问题已经解决了。
- 请注释解释关闭工单的决定。
- 如果他们有办法改进工单重新开启,让他们知道。
- 如果票是重复的,请参考原始票。 还可以通过在原始故障单中留下评论来交叉引用已关闭的故障单 - 这允许访问有关报告的错误或请求的功能的更多相关信息。
- 有礼貌。没有人喜欢关闭他们的票。 这可能令人沮丧,甚至令人沮丧。 避免拒绝人们为 Django 做出贡献的最好方法是礼貌和友好,并就他们将来如何改进这张票和其他票提供建议。
工单可以通过多种方式收尾:
- *; 已修复
- 在Django中添加补丁并修复问题后使用。
- *; 无效
- 在发现票证不正确时使用。 这意味着工单中的问题实际上是用户错误的结果,或者描述了 Django 以外的问题,或者根本不是错误报告或功能请求(例如,一些新用户提交支持查询作为门票)。
- *; 不会修复
- 当某人决定该请求不适合在 Django 中考虑时使用。 有时,一个工单被关闭为“wontfix”,并要求记者在 django-developers 邮件列表上开始讨论,如果他们感觉与关闭工单的人提供的理由不同。 其他时候,邮件列表讨论先于关闭票证的决定。 在重新打开以“wontfix”关闭的票证之前,请始终使用邮件列表来达成共识。
- *; 重复
- 当另一张票涉及同一问题时使用。 通过关闭重复的工单,我们将所有讨论集中在一个地方,这对每个人都有帮助。
- *; 对我有用
- 当故障单不包含足够的细节来复制原始错误时使用。
- *; 需要信息
- 当票证不包含足够的信息来复制报告的问题但可能仍然有效时使用。 当提供更多信息时,应重新打开票证。
如果您认为工单被错误关闭——因为您仍然有问题,或者它在其他地方弹出,或者分类员犯了一个错误——请重新打开工单并提供更多信息。 同样,请不要重新打开标记为“wontfix”的票证,而是将问题提交给 django-developers。
我能帮你怎么做分类?
分类过程主要由社区成员驱动。 真的,ANYONE 可以提供帮助。
要参与其中,请从 在 Trac 上创建一个帐户开始。 如果您有账户但忘记了密码,您可以使用密码重置页面重置它。
然后,你可这样帮忙:
- 以“无效”、“作品形式”或“重复”或“不会修复”的形式关闭“未审核”工单。
- 当描述太稀疏而无法操作时,或者当它们是需要在 django-developers 上进行讨论的功能请求时,将“未审查”票作为“needsinfo”关闭。
- 更正错误设置的故障单的“需要测试”、“需要文档”或“有补丁”标志。
- 设置“Easy picks”标志为小而相对简单的票证。
- 设置未分类的工单的type。
- 检查旧票是否仍然有效。 如果工单很长时间没有看到任何活动,则可能是问题已解决,但工单尚未关闭。
- 识别门票中的趋势和主题。 如果有很多关于 Django 特定部分的错误报告,则可能表明我们应该考虑重构该部分代码。 如果某个趋势正在出现,您应该在 django-developers 上提出它以供讨论(参考相关票证)。
- 验证其他用户提交的补丁是否正确。 如果它们是正确的并且还包含适当的文档和测试,则将它们移至“准备签入”阶段。 如果它们不正确,请发表评论以解释原因并设置相应的标志(“补丁需要改进”、“需要测试”等)。
但是,我们确实要求在工单数据库中工作的所有普通社区成员:
- 请不要将您自己的门票宣传为“准备签到”。 您可以将您审核过的其他人的票标记为“准备签入”,但您应该至少让其他社区成员审核您提交的补丁。
- 请不要在没有向django-developers发布消息以达成共识的情况下撤消决定。
- 如果您不确定是否应该进行更改,请不要进行更改,而是在票证上留下您的疑虑,或者向 django-developers 发送消息。 不确定是可以的,但您的意见仍然很有价值。
平等回归
回归是一些较新版本的 Django 中存在但在较旧版本中不存在的错误。 一个非常有用的信息是引入回归的提交。 了解导致行为更改的提交有助于确定更改是有意的还是无意的副作用。 以下是您如何确定这一点。
首先为该问题的 Django 测试套件编写回归测试。 例如,我们会假装我们正在调试迁移中的回归。 在您编写测试并确认它在最新的 master 上失败后,将它放在一个单独的文件中,您可以独立运行。 在我们的例子中,我们假设我们创建了 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 票证上报告您的结果,并将回归测试作为附件包含在内。 当有人为该错误编写修复程序时,他们已经将您的测试作为起点。