How the issue tracker works
The Dart SDK repo contains a large number of tools and libraries maintained by a variety of sub-teams. Having them all in one repo makes it easier to land sweeping changes across those components, but it comes at the expense of a big, unwieldy issue tracker. To tame that chaos, we use the labels and policies explained here.
Like many modern software teams, Dart uses a pull model to assign tasks to people. Most issues are assigned to a team (using the area labels below), but not proactively assigned to an individual. When a person begins active work on an issue, they assign the issue to themselves.
If you see an issue with a person assigned to it, it's usually in-progress. This isn't always the case. Sometimes an issue is assigned to someone because we know they will be the one to fix it, but they haven't started yet. When work gets paused (sometimes for a long time) the assignee might not unassign themselves.
Labels help us narrow down issues to the subsets each team or person cares about. They let us count related issues to compare areas or see trends over time. And they help the larger community understand what we're working on and the state of their bugs.
For consistency, label names are kebab-case: lowercase words separated
by hyphens. Since we have a lot of labels, most of them are categorized. The
first word in the label name usually indicates the category. The labels and
categories are:
These are the main labels that people on the Dart team care about. Each area label defines a subteam (sometimes just one person) that owns issues and is responsible for resolving them or passing them to another area.
Every issue must have a single area label. We've found that when labels have no area, or multiple areas, it's not clear who is responsible for it, and it falls through the cracks. If a single issue needs work from multiple teams, then it's split into two or more issues, each one assigned to a single area.
The "area-meta" area is special. A meta-issue groups a set of other issues together to coordinate work across multiple teams. The issue usually describes the overall plan at a high level and then links to the specific issues related to it. Since no one team is responsible for "area-meta", an issue with that label should also be assigned to a single person that is responsible for tracking the status of the individual linked issues and closing the meta-issue when everything is complete.
For issues on our web products, this tracks which browser is affected by the issue. We don't always apply this diligently, so the absence of this could mean either "all browsers" or "we haven't investigated which browsers are affected". Likewise, the presence of this doesn't necessarily mean other browsers are in the clear.
If an issue seriously affects a key partner, this tracks who they are. This helps us prioritize the issue and makes sure we keep them in the loop on it.
We also use this to track Dart subteams that are affected by an issue owned by another area. For example, if someone files a bug that the VM is failing to display a certain static error, it would likely have "area-cfe" (because the front end team handles static errors) and "customer-vm" because that's where the error isn't being surfaced.
Similar to browser, this tracks which operating systems an issue manifests on. Again, we aren't super diligent about this. The presence of this label indicates that we know it does have a problem on that OS, but may still possibly affect others.
Priority labels indicate the team's urgency around resolving the issue. They roughly mean:
-
P0: "World is on fire." Issues like multiple products unusable, a security issue exposing personal information, or a dramatic performance regression. As many team members as needed should drop everything to fix this.
-
P1: "Something's broken." A single project is unusable or has many test failures. It should be fixed before resuming normal work.
-
P2: "Business as usual." These are normal issues and feature requests that we can work into our schedule without any particular urgency.
-
P3: "If you get a chance." Cosmetic or minor bugs with no urgency and low visibility. Polish or nice-to-haves.
Almost every issue should have exactly one of these labels.
As the name implies, these labels are applied to closed issues, and indicate why it was closed. In a perfect world, every issue filed would uniquely identify a real, important problem and every closed issue would be fixed.
Alas, sometimes issues are duplicates of others, are too confusing, or we simply don't have the time to do anything about it. We take every issue seriously, but we also have to maximize the value we provide in the limited time we have, which requires some trade-offs.
If an issue is closed without a closed label, that implies it is fixed. There should usually be a link to the commit that fixes the issue or a comment explaining it. Otherwise, it should have one of the resolution labels applied, and often a comment explaining why that resolution was chosen.
The reasons are:
-
closed-as-intended: This is one of the most contentious reasons to close an issue. This label means the current behavior is what we want, even though it's clearly not what the person who filed the issue wants.
When possible, the person closing the bug should write a comment explaining why the current behavior is preferred. Often, there are constraints or interactions with other systems that prevent us from supporting the requested behavior. Sometimes it's simply making a trade-off between users who want different things.
-
closed-cannot-reproduce: It's hard to verify that a fix is the right one without being able to see the underlying problem first. Sometimes this happens because the bug got fixed before anyone looked at the issue. Other times, the problem is still there but the investigator failed to get it to manifest. This resolution means they weren't able to make the issue happen and they believe it's likely to not be a problem any more.
If an issue you filed is closed with this but it is still valid, consider adding a comment with more detailed reproduction steps so the issue can be re-opened.
-
closed-duplicate: There is already another issue that tracks this change. When an issue is closed with this label, it should also have a comment that links to the other issue it is a duplicate of.
Determining if two issues are duplicates often relies on understanding internal architecture and implementation details. Sometimes two issues look like the same problem but need to get solved in different ways. Other times, two seemingly-different issues have the same underlying cause.
Because we use issues to track units of work, we treat issues as duplicates if they will be solved by a single change. This means that when we close one issue, we are not discarding the information in the issue or the important discussion it might have. That's still there and easy to find since the open issue links to it. It simply means we think there is only one task to perform that will address both issues, so there is no need to keep both open.
In general, when deduplicating issues, we tend to keep the older one open unless the newer one is clearly more useful.
-
closed-invalid: Sometimes, despite everyone's best intentions, we can't figure out what an issue description is trying to convey. Users sometimes file issues on our repo for completely unrelated products. Mistakes happen. This label means we couldn't make heads or tails of the issue.
Most of the time, we try to avoid this and instead use "needs-info" to get clarification from the person who filed the issue.
-
closed-obsolete: The issue has been around for a long time with no activity. No one has worked on a solution and people don't seem to be clamoring for one either. The problem may have been fixed without someone realizing there was an issue. Sometimes stuff that was important turns out not to be later when needs change.
In that case, there's little value keeping a zombie issue around and it will get closed. It's always OK to re-open the issue or file a new one of it turns out the problem is still relevant. This label is often applied manually by people when closing bugs, but also by the bot according to our expiration policy below.
-
closed-not-planned: Possibly the saddest label. This is for issues where the request is valid but isn't expected to happen. Sometimes this is because other higher-priority enhancements would directly conflict with it. Often, it's simply a matter of not having enough time to get to it.
When an issue is closed as not planned, that doesn't mean it will never happen. Priorities and capacity changes over time and it's entirely possible that it will come to the fore in the future. But in the meantime, we think it more clearly communicates the team's current priorities to close the issue instead of letting it linger even though we have no intent to allocate time to it.
An issue's type categorizes the kind of problem entailed, or the nature of the work required to solve it. There are a handful:
-
type-bug: Issues with this label describe problems where the current behavior of the system is wrong and is not intended to act this way. It could be as severe as a crash or a more subtle misbehavior, but it should be obviously wrong in a way that almost no user wants.
-
type-code-health: This tracks internal changes to our tools and workflows to make them cleaner, simpler, or more maintainable in ways that aren't user visible.
-
type-documentation: A request to add or improve documentation. Since most of the high level docs like the pages on dartlang.org are managed in other repositories, this ends up not being particularly common and is mostly API-level doc comments.
-
type-enhancement: Every request for a concrete change to a tool that isn't a bug is an enhancement. These are new features, refinements to existing features, or other changes where the current behavior was intended but may no longer be desired or sufficient. Most issues around changing code get this label.
-
type-performance: These are issues where the observed behavior is correct but the efficiency leaves something to be desired. "Performance" varies across a number of axes: execution time, memory usage, startup time, etc.
-
type-security: The scariest kind of issue. These are problems related to user privacy or the ability of a malicious actor to take over a system.
-
type-task: Tasks track work that needs to be done but where the result isn't a change to code or documentation. This is things like moving data around, publishing packages, tweaking servers or other infrastructure, etc.
Any given issue should have exactly one of these. If not, it's probably still waiting to be triaged.
Subteams often have their own labels that are only meaningful for a certain product or system. Those labels start with the name of the team's area. For example, "analyzer-", "vm-", etc. Area-specific labels are owned by the respective team and it's up to that team to manage how the labels are used, what they mean, and when they can be removed.
There are a few other miscellaneous labels you might run into:
-
blocked: This marks an issue where the team is unable to make progress on it because of some external constraint or other team. There should be a comment explaining what it's blocked on. When possible, it will link directly to another issue that is blocking this one.
-
cla: yes, cla: no: Before we can accept a change from a non-Google contributor, they must sign our contributor license agreement. We have a bot that requests that they do that and tracks whether they have using these labels.
-
contributions-welcome: This marks an issue which has been vetted as "legitimate," and which the owning subteam would welcome a contribution from an external developer. Resolving an issue marked with this label should not be overly difficult, and should not require a great amount of code. This label is typically applied to bugs and documentation requests, rather than feature requests, due to the lower cost of review and maintenance.
-
merge-to-dev, merge-to-stable: These are used to track requests to cherry-pick a change from master to one of the release branches.
-
needs-info: Like the name says, this means we need more information. This is often because the initial issue description is unclear. Other times, it means we have done some work fixing the issue and want someone else to validate the solution.
When someone applies this label, they should also write a comment explaining what information or clarification they are looking for. Issues like this have a tendency to go stale because we can't make progress on it and the original submitter may have moved on. This means that we are likely to close an issue with this label if it hasn't had any activity in 60 days. If you care about keeping the issue alive, please try to provide the information it needs.
FAQ about the Dart VM