分类工单

Django使用 Trac 来管理代码基本库上的工作。Trac 是一个由社区管理的花园，里面有人们发现的bug和人们希望看到的功能。就像在任何一个花园里一样，有时有杂草需要拔除，有时有些花和蔬菜需要采摘。我们需要你的帮助，把其中的一个从另一个中挑出，最终我们都能从中受益。

Like all gardens, we can aspire to perfection but in reality there’s no such thing. Even in the most pristine garden there are still snails and insects. In a community garden there are also helpful people who — with the best of intentions — fertilize the weeds and poison the roses. It’s the job of the community as a whole to self-manage, keep the problems to a minimum, and educate those coming into the community so that they can become valuable contributing members.

Similarly, while we aim for Trac to be a perfect representation of the state of Django’s progress, we acknowledge that this will not happen. By distributing the load of Trac maintenance to the community, we accept that there will be mistakes. Trac is “mostly accurate”, and we give allowances for the fact that sometimes it will be wrong. That’s okay. We’re perfectionists with deadlines.

We rely on the community to keep participating, keep tickets as accurate as possible, and raise issues for discussion on our mailing lists when there is confusion or disagreement.

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

分诊工作流

不幸的是，并不是工单跟踪程序中的所有bug报告和功能请求都提供 required details 。很多工单都有补丁，但这些补丁并不满足一个 good patch 的要求。

One way to help out is to triage tickets that have been created by other users.

大多数工作流都是基于工单的 :ref:`triage stages ` 。每个阶段都描述了在其生命周期中，给定的工单在任何时间的位置。除了一些标志，这个属性可以很容易地告诉我们每张工单在等待什么和谁。

既然一张图片胜过千言万语，那就从这里开始吧：

在这张图表中我们有两个角色：

• Committers: people with commit access who are responsible for making the final decision to merge a patch.
• 工单分拣员：Django社区中选择参与Django开发过程的任何人。我们的Trac装置有意对公众开放，任何人都可以对工单进行分类。Django是一个社区项目，我们鼓励 triage by the community 。

举个例子，我们可以看到一张普通工单的生命周期：

• Alice创建一个工单并发送一个不完整的请求（没有测试，实现也不正确）。
• Bob reviews the pull request, marks the ticket as “Accepted”, “needs tests”, and “patch needs improvement”, and leaves a comment telling Alice how the patch could be improved.
• Alice更新pull请求，添加测试（但不更改实现）。她把两个旗子摘了下来。
• Charlie检查pull请求并用另一条关于改进实现的注释重置“patch needs improvement”标志。
• Alice更新了pull请求，修复了实现。她去掉了“patch needs improvement”的标志。
• Daisy检查pull请求并将工单标记为“Ready for checkin”。
• Jacob，一个提交者，检查pull请求并合并它。

有些工单需要的反馈比这少得多，但同样有些工单需要更多的反馈。

分类阶段

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

没有审阅

没有任何人对工单是否包含有效问题、可行功能或是否应因任何原因关闭而对工单进行审阅。

已接受

大灰色区域！“已接受”的绝对含义是，工单中描述的问题是有效的，并且正处于处理的某个阶段。除此之外，还有几个考虑因素：

• 已接受并且没有标识

  工单是有效的，但是还没有人提交补丁。通常这意味着您可以安全地开始为它编写补丁。对于可接受的bug，这通常比接受的特性更真实。对于一个已经被接受的bug的工单意味着这个问题已经被至少一个trigger验证为合法的bug，并且如果可能的话应该被修复。一个被接受的新特性可能只意味着一个试验者认为该特性将是好的，但这本身并不代表一致的观点，也不意味着某个补丁将被接受。如果您有疑问，请在编写大量补丁之前寻求更多反馈。

• 已接受并且有补丁

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

• 已接受并且有补丁，需要…

  这意味着工单已经过审核，需要进一步的工作。“需求测试”和“需求文档”是不言而喻的，“补丁需要改进”通常会在工单上附上注释，解释需要改进的代码。

准备收入

除了提供修补程序的人之外，社区的任何成员都会检查该工单，并发现它满足提交就绪修补程序的所有要求。提交者现在需要在提交之前对补丁进行一次最终审查。请参阅 New contributors’ FAQ 中的“我的工单永远在RFC中！我该怎么办？”

几天/可能

图中未显示此阶段。它很少用于跟踪高层次的想法或长期特性请求。

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

其他分类属性

A number of flags, appearing as checkboxes in Trac, can be set on a ticket:

有补丁

这意味着工单有一个关联的 patch 。这些将被审阅，看看补丁是否“良好”。

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

需要文档

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

需要测试

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

补丁需要改进

此标志表示虽然工单 *有*个补丁，但还没有完全准备好检入。这可能意味着补丁没有干净地应用，实现中存在缺陷，或者代码不符合我们的标准。

容易挑选

需要小的，容易的补丁的工单。

类型

工单应该按*类型*分类

• 新特性

  为了添加一些新东西。

• 错误

  指☞一些损坏的或者行为与预期不符的地方。

• 清理/优化

  指那些没有东西被破坏，同时有一些东西可以变得更干净、更好、更快、更强的地方。

组件

工单应该被分类到*组件*中，指出它们属于Django代码库的哪个区域。这使得工单更有条理，更容易找到。

严重性

severity 属性用于标识阻止内容，即在发布下一个Django版本之前应该解决的问题。这些问题通常是导致回滚至早期版本的错误，或者可能导致严重的数据丢失。这个属性很少使用，而且绝大多数罚单的严重性都是“正常”。

版本

可以使用*version*属性来指示在哪个版本中发现了报告的bug。

UI/UX

此标志用于与用户界面和用户体验问题相关的工单。例如，此标志适用于表单或管理后台接口界面中面向用户的功能。

副本

您可以将您的用户名或电子邮件地址添加到该字段，以便在对工单进行新的投稿时收到通知。

关键词

使用此字段，您可以用多个关键字标记工单。例如，将同一主题的多张工单组合在一起是很有用的。关键字可以是逗号或空格分隔。关键字搜索在关键字中的任何位置查找关键字字符串。例如，单击关键字为“form”的工单将生成带有关键字标记的类似工单，这些关键字包含“formset”、“modelformset”和“ManagementForm”。

关闭工单

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

如果您确实关闭了工单，则应始终确保以下事项：

• 确认问题已经解决了。
• 请注释解释关闭工单的决定。
• 如果他们有办法改进工单重新开启，让他们知道。
• 如果工单重复了，请参考原始工单。还可以通过在原始工单中留下注释来交叉引用已关闭的工单——这允许访问有关报告的错误或请求的功能的更多相关信息。
• **要有礼貌。**没有人喜欢关闭他们的工单。这可能会让人沮丧甚至沮丧。避免让人们拒绝为 Django 贡献的最好方法是礼貌友好，并为他们将来如何改进这张工单和其他工单提供建议。

工单可以通过多种方式收尾：

• 已修复

  在Django中添加补丁并修复问题后使用。

• 无效

  如果发现工单不正确，则使用。这意味着工单中的问题实际上是用户错误的结果，或者描述的是Django之外的问题，或者根本不是bug报告或特性请求（例如，一些新用户将支持查询作为工单提交）。

• 不会修复

  当某人认为请求不适合在Django中考虑时使用。有时，一张工单会以“wontfix”的形式关闭，请求报告者在| django开发人员的邮件列表 |中讨论，如果他们觉得与关闭工单的人提供的理由不同。其他时候，邮件列表讨论会在决定关闭工单之前进行。在重新打开关闭为“wontfix”的工单之前，请始终使用邮件列表来获得共识。

• 重复

  当另一张工单涵盖同一问题时使用。通过关闭重复工单，我们将所有讨论放在一个地方，这对每个人都有帮助。

• 对我有用

  当工单中没有足够的细节来复现原始错误时使用。

• 需要信息

  当工单不包含足够的信息来复现报告的问题，但可能仍然有效时使用。提供更多信息后，应重新打开工单。

如果您认为错误地关闭了工单——因为您仍然有问题，或者它在其他地方弹出，或者审阅人员出错——请重新打开工单并提供进一步的信息。同样，请不要重新打开标记为“wontfix”的工单，而是将问题提交给| django developers |。

我能帮你怎么做分类？

分流过程主要由社区成员推动。真的，**任何人**都能帮上忙。

要想参与其中，首先要 “在Trac上创建一个账户”_ 。如果您有账户但忘记了密码，可以使用 “密码重置页”_ 重置它。

然后，你可这样帮忙：

• 以“无效”、“工作表”或“复制”或“wontfix”关闭“未审核”票据。
• 当描述太少而无法操作时，或者当它们是需要在| django developers |中讨论的功能请求时，将“unreview”工单作为“needsinfo”关闭。
• 当描述太少而无法操作时，或者当它们是需要在| django developers |中讨论的功能请求时，将“unreview”工单作为“needsinfo”关闭。
• 配置 “Easy pickings“ 标志，用于较小且相对简单的工单。
• 设置尚未分类的工单的 类型 。
• 检查原工单是否仍然有效。如果一个工单在一长段时间里未发现任何活动，则有可能其问题已经修复但工单尚未关闭。
• 确定工单的趋势和主题。如果有很多关于Django的特定部分的bug报告，这可能表明我们应该考虑重构这部分代码。如果一种趋势正在出现，你应该把它提出来，在 django-developers 上讨论（参考相关问题）。
• 验证其他用户提交的修补程序是否正确。如果它们是正确的并且还包含适当的文档和测试，那么将它们移到“准备签入”阶段。如果它们不正确，请留下注释解释原因并设置相应的标志（“补丁需要改进”、“需要测试”等）。

注解

Reports page 包含指向许多有用的Trac查询的链接，其中包括一些对筛选工单和查看上面建议的修补程序很有用的查询。

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

但是，我们确实要求在工单数据库中工作的所有普通社区成员：

• 请 不要 将您自己的工单升级为 “准备接受”。您可以将您已审核过的其他人的工单标记为“准备接受”，但您至少应有一名其他社区成员来审核您提交的补丁程序。
• 请 不要 未向 django-developers 群组发布一条寻求共识的消息就撤销决定。
• 如果不确定是否应该进行更改，请不要进行更改，而要在工单上留下您的疑虑的注释或向 django-developers 发送消息。 不确定是可以的，但是您的输入仍然很有价值。

平等回归

回归是一些较新版本的Django中存在，而较旧的版本中没有的错误。 引入回归的提交是非常有用的信息。了解导致行为改变的提交有助于识别改变是有意的还是无意的副作用。以下是您如何确定这个的。

Begin by writing a regression test for Django’s test suite for the issue. For example, we’ll pretend we’re debugging a regression in migrations. After you’ve written the test and confirmed that it fails on the latest main branch, put it in a separate file that you can run standalone. For our example, we’ll pretend we created tests/migrations/test_regression.py, which can be run with:

$ ./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工单上报告您的结果，并在附件中包含回归测试。当某人为该错误编写修复程序时，他们已经以您的测试为起点。