# Django 6.0.7 documentation

# 分类工单

Django 使用 Trac 来管理代码库上的工作。 Trac 是一个由社区维护的花园，里面记录了人们发现的错误和人们希望添加的功能。就像任何花园一样，有时候需要清除杂草，有时候则需要采摘鲜花和蔬菜。我们需要您的帮助来区分其中的差异，最终我们都会从中受益。

就像所有花园一样，我们可以追求完美，但实际上并不存在完美无缺的事物。即使在最洁净的花园中，仍然会有蜗牛和昆虫存在。在社区花园中，也会有热心的人们——怀着最好的意图——给杂草施肥，却误伤玫瑰。整个社区的任务是自我管理，将问题最小化，并教育那些加入社区的人，使他们成为有价值的贡献成员。

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.

我们依靠社区继续参与，尽可能保持工单的准确性，并在出现困惑或分歧时在 Django 论坛 中提出问题以供讨论。

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

## 分类工作流

不幸的是，并非所有工单跟踪器中的错误报告和功能请求都提供了所有 必需的细节。一些工单提出了解决方案，但这些方案不一定满足所有 遵循贡献指南 的要求。

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

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

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

We have four roles in this diagram. Maintainers (also known as Fellows) usually take part in all of them, but anyone in the Django community can participate in any role except merger. The merger role is granted by a vote of the Steering Council.

- Triagers: anyone can take on this role by checking whether a ticket describes a real issue and keeping the tracker organized.

- Bug fixers: anyone can contribute by opening a pull request and working on a solution for a ticket.

- Reviewers: anyone can review pull requests and suggest improvements.

- Mergers: people with commit access who make the final decision to merge a change.

When we say anyone, we mean you!

Our Trac system and GitHub repositories are intentionally open to the public. Anyone can help by working on tickets, triaging tickets and reviewing changes. Django is a community project, and we encourage triage and collaboration by the community. We truly want you to help!

举个例子，这里有一张典型工单的生命周期：

- Alice创建一个工单并发送一个不完整的拉取请求（没有测试，实现也不正确）。

- Bob reviews the pull request, marks the ticket as "Accepted", sets the flags "needs tests" and "patch needs improvement", and leaves a comment explaining how Alice can improve the patch. This puts the ticket automatically into the "waiting on author" queue within the "accepted" stage.

- Alice更新pull请求，添加测试（但不更改实现）。她把两个旗子摘了下来。工单移至“需要 PR 审核”队列。

- Charlie reviews the pull request, sets the "patch needs improvement" flag again, and leaves another comment suggesting changes to the implementation. The ticket moves back to the "waiting on author" queue.

- Alice更新了pull请求，修复了实现。她去掉了“patch needs improvement”的标志。工单再一次移至“需要 PR 审核”队列。

- Daisy检查pull请求并将工单标记为“Ready for checkin”。

- Jacob，一位 合并者，审查了拉取请求并将其合并。

Some tickets move through these steps quickly, while others take more time and discussion. Each contribution helps Django improve.

## 分类阶段

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

### 没有审阅

The ticket has not been reviewed by anyone who felt qualified to make a judgment about whether the ticket contained a valid issue or ought to be closed for any reasons. Unreviewed tickets appear in the "triage" queue.

Unreviewed tickets may receive additional refinement before being accepted. Unless you are both the author of the ticket and intending to submit a patch, unreviewed tickets should not be claimed.

### 已接受

The absolute meaning of "accepted" is that the issue described in the ticket is valid and actionable. It is broken out into three queues:

- 需要补丁 （已接受并且没有标识）

  工单是有效的，但还没有人提交补丁。通常这意味着你可以安全地开始为其编写修复程序。对于已接受的错误，这通常比已接受的功能更常见。一个已接受的错误工单意味着至少一位分类者已验证该问题是一个合法的错误——如果可能的话，应该进行修复。一个已接受的新功能可能只意味着一位分类者认为该功能很好，但这并不代表共识观点，也不能确定该功能的补丁会被接受。如果你有疑问，在编写大量贡献之前寻求更多反馈。

  For new features, accepted tickets should only exist after the idea has gone through the appropriate process for suggesting new features and received community and Steering Council approval, or been accepted in a DEP.

- 需要 PR 审核 （已接受并且有补丁）

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

- Waiting On Author (Accepted + Has Patch + Needs fixes)

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

### 准备收入

工单已由社区中除提供补丁者之外的任何成员审查，并发现其满足提交准备贡献的所有要求。现在需要 合并者 在提交之前进行最终审查。

有很多拉取请求，你的补丁可能需要一些时间来进行审查。请查看 贡献代码 FAQ 获取一些关于此的想法。

### 几天/可能

This stage isn't shown on the diagram. It's used sparingly to keep track of long-term changes.

These tickets are uncommon and overall less useful since they don't describe concrete actionable issues.

## 其他分类属性

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

### 有补丁

This means the ticket has an associated solution. These will be reviewed to ensure they adhere to the documented guidelines.

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

### 需要文档

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

### 需要测试

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

### 补丁需要改进

这个标志意味着尽管工单 有 一个解决方案，但它还没有准备好被检入。这可能意味着补丁不再干净地应用，实现中存在缺陷，或者代码不符合我们的标准。

### 容易挑选

需要简单、容易更改的工单。

### 类型

工单应该按*类型*分类

- 新特性

    为了添加一些新东西。

- 错误

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

- 清理/优化

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

### 组件

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

### 严重性

severity 属性用于标识阻止问题，也就是在发布下一个 Django 版本之前应该修复的问题。通常，这些问题是导致与早期版本的不兼容性或可能导致严重数据丢失的错误。这个属性很少被使用，绝大多数工单的严重性都是 "Normal"（正常）。

### 版本

The version attribute indicates the earliest version in which the bug was reproduced. During triage, this field can be updated, but there is no need to make further updates when that version goes out of support. The field should not be reset to "dev" to show the issue still exists: instead, the tested commit hash can be noted in a comment.

### UI/UX

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

### 副本

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

### 关键词

使用此字段，您可以为一个工单添加多个关键词标签。这在将几个相关的工单分组时非常有用。关键词可以用逗号或空格分隔。关键词搜索会在关键词的任何位置查找关键词字符串。例如，点击带有关键词 " form " 的工单会显示带有包含字符串 " formset "、" modelformset " 和 " ManagementForm " 的类似关键词标记的工单。

## 关闭工单

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

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

- 确认问题已经解决了。

- 请注释解释关闭工单的决定。

- 如果他们有办法改进工单重新开启，让他们知道。

- 如果工单重复了，请参考原始工单。还可以通过在原始工单中留下注释来交叉引用已关闭的工单——这允许访问有关报告的错误或请求的功能的更多相关信息。

- 要有礼貌。 没有人喜欢关闭他们的工单。这可能会让人沮丧甚至沮丧。避免让人们拒绝为 Django 贡献的最好方法是礼貌友好，并为他们将来如何改进这张工单和其他工单提供建议。

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

- 已修复

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

- 无效

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

- 不会修复

    Used when someone decides that the request isn't appropriate for consideration in Django. Sometimes a ticket is closed as "wontfix" with a request for the reporter to start a discussion on the Django Forum if they feel differently from the rationale provided by the person who closed the ticket. Other times, a discussion precedes the decision to close a ticket. Always use the forum to get a consensus before reopening tickets closed as "wontfix".

- needsnewfeatureprocess

    Used when the ticket merits a new feature, which will need to get community input and support. See the process for suggesting new features.

- 重复

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

- 对我有用

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

- 需要信息

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

If you believe that the ticket was closed in error -- because you're still having the issue, or it's popped up somewhere else, or the triagers have made a mistake -- please reopen the ticket and provide further information. Again, please do not reopen tickets that have been marked as "wontfix" or "needsnewfeatureprocess". For "wontfix" tickets, bring the issue to the Django Forum instead. For "needsnewfeatureprocess" tickets, propose the feature through the new features process.

## 我能怎么帮助开发工作？

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

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

然后，你可这样帮忙：

- 以“无效”、“对我有效”、“重复”、“不会修复”或“需要新功能流程”关闭“未审核”工单。

- 当问题描述过于简略，无法采取行动时，以“需要信息”关闭“未审核”的工单。

- 纠正那些设置错误的“需要测试”、“需要文档说明”或“有补丁”的标签。

- 配置 "Easy pickings" 标志，用于较小且相对简单的工单。

- 设置尚未分类的工单的 类型 。

- 检查原工单是否仍然有效。如果一个工单在一长段时间里未发现任何活动，则有可能其问题已经修复但工单尚未关闭。

- Identifying trends and themes in the tickets. If there are a lot of bug reports about a particular part of Django, it may indicate we should consider refactoring that part of the code. If a trend is emerging, you should raise it for discussion (referencing the relevant tickets) on the Django Forum.

- 验证其他人提交的解决方案是否正确。如果它们是正确的并且包含适当的文档和测试，则将它们移至“准备检入”阶段。如果它们不正确，则留下评论解释原因并设置相应的标志（“补丁需要改进”，“需要测试”等）。

Note

报告页面 包含许多有用的 Trac 查询链接，其中包括一些对分类工单和审查建议非常有用的查询，如上所述。

You can also find more 对新贡献者的建议.

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

- Please don't promote your own tickets to "Accepted". Another community member should review the report and set this stage after reproducing and confirming the issue.

- Please don't promote your own tickets to "Ready for checkin". You may mark other people's tickets that you've reviewed as "Ready for checkin", but you should get at minimum one other community member to review a patch that you submit.

- Please don't reverse a decision without posting a message to the Django Forum to find consensus.

- If you're unsure if you should be making a change, don't make the change but instead leave a comment with your concerns on the ticket, or post a message to the Django Forum. It's okay to be unsure, but your input is still valuable.

## 平等回归

回归是一些较新版本的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 个提交）。检查测试是否失败。如果是的话，将该点标记为 "bad"（`git bisect bad`），然后检出更早的修订版并重新检查。一旦找到一个测试通过的修订版，请将其标记为 "good"：

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

## Reviewing patches

A great way to learn the Django codebase is to help review patches. It allows you to focus on a fixed scope of Django with a particular perspective. Plus, Django tends to receive more patches than it can review which causes the review queue to build up. Contributors can help Django tremendously by reviewing patches.

The review queue is defined by tickets in Trac that are in the "Accepted" state with the flag "has patch" set and the flags "patch needs improvement", "needs tests" and "needs documentation" unset. There is also a set of Pull Requests in GitHub with the "no ticket" label that can be reviewed.

### Code review process

The general process to reviewing a patch for Django is as follows:

1. Pick a patch to review. This can be from the review queue or the Pull Requests in GitHub with the "no ticket" label. If you're new, pick a specific component to stick with. Django is a big codebase, so it's best to contribute consistently with a narrow focus and grow it slowly.

2. Pull the branch. See the 处理 pull 请求, including the git alias to make checking out other pull requests easier.

3. Check the tests. If the ticket is for a bug, there should be a regression test. Confirm that the test fails if the change is reverted. Check that the tests are adequately covering the code and logic as well. See 贡献清单.

4. Test in your own Django project. See 安装开发版本 for how. Explore the user interface and user experience with the change. Does it feel right? Can you break it? Another approach is to assume everything is wrong. Can you demonstrate to yourself that each piece is correct?

5. Check the documentation. Is the documentation understandable? Does it provide the information the reader needs at that moment? Does it read well? Is it consistent with the documentation before and after it? See 在本地构建文档.

6. Are you happy with the patch? This is fairly subjective, but that's fine. You should ask, does the approach make sense to you and is there another way to do it that's better? Also ask yourself, is the scope of the change appropriate? Are things named appropriately? Renaming things is slow and challenging in Django, so we should try to get it right from the start. Are there backwards compatibility concerns? Lastly, are there any other general concerns such as things that may worry you or that should be looked into?

7. Review your feedback. Before you submit your feedback, consider the feedback you want to share. It takes courage to open a Pull Request, we should be thoughtful and considerate of the leap the author has made. If there are nitpicky or small suggestions, use GitHub's suggestion feature. If the approach isn't what you expected, consider asking the author why before requesting several changes. Seek to understand their reasoning first.

8. Submit feedback on GitHub and update flags, "patch needs improvement", "needs tests", and "needs documentation", as needed. This will move the ticket to the "waiting for author" queue. If you have given a specific type of code review, please indicate that on the Pull Request.

### Types of code reviews

Not everyone will or should give the same type of code review. Having a diverse set of opinions and experiences helps Django be better. If you are providing a specific review, please indicate that on the Pull Request in GitHub. Below are some of the types of code review you can perform:

- Accessibility review. Does it conform to our 可访问性标准?

- Patch style and contribution process review.

- Usability and developer experience review.

  - Use the change and provide feedback from that experience.

  - Are the APIs and documentation accessible and well explained?

- Domain expertise review. Do you have a personal expertise that is relevant such as databases, HTTP, security, etc?

- Benchmarking and performance review. There are benchmarking tests, but sometimes changes require additional testing.

  - Utilize django-asv 基准测试 to check performance over time.

  - Run benchmark tests by labeling the pull request with "benchmark".