| > [!IMPORTANT] | |
| > This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. | |
| > Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - | |
| > removing this header - or send a CL to delete the file. | |
| --- | |
| 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. | |
| ## Assignment | |
| 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 | |
| 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: | |
| ### Area ("area-") | |
| 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. | |
| ### Browser | |
| 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. | |
| ### Customer ("customer-") | |
| 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. | |
| ### OS ("os-") | |
| 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 | |
| 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. | |
| ### Closed ("closed-") | |
| 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. | |
| ### Type ("type-") | |
| 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. | |
| ### Area-specific labels | |
| 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, "devexp-", "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. | |
| ### Other labels | |
| 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][cla]. 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 main to one of the [release | |
| branches][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. | |
| [area-cfe]: https://github.com/dart-lang/sdk/labels/area-cfe | |
| [area-meta]: https://github.com/dart-lang/sdk/labels/area-meta | |
| [blocked]: https://github.com/dart-lang/sdk/labels/blocked | |
| [branches]: Branches-and-releases.md | |
| [cla: no]: https://github.com/dart-lang/sdk/labels/cla%3A%20no | |
| [cla: yes]: https://github.com/dart-lang/sdk/labels/cla%3A%20yes | |
| [cla]: https://cla.developers.google.com/about/google-individual | |
| [closed-as-intended]: https://github.com/dart-lang/sdk/labels/closed-as-intended | |
| [closed-cannot-reproduce]: https://github.com/dart-lang/sdk/labels/closed-cannot-reproduce | |
| [closed-duplicate]: https://github.com/dart-lang/sdk/labels/closed-duplicate | |
| [closed-invalid]: https://github.com/dart-lang/sdk/labels/closed-invalid | |
| [closed-not-planned]: https://github.com/dart-lang/sdk/labels/closed-not-planned | |
| [closed-obsolete]: https://github.com/dart-lang/sdk/labels/closed-obsolete | |
| [contributions-welcome]: https://github.com/dart-lang/sdk/labels/contributions-welcome | |
| [customer-vm]: https://github.com/dart-lang/sdk/labels/customer-vm | |
| [dartlang.org]: https://www.dartlang.org | |
| [merge-to-dev]: https://github.com/dart-lang/sdk/labels/merge-to-dev | |
| [merge-to-stable]: https://github.com/dart-lang/sdk/labels/merge-to-stable | |
| [needs-info]: https://github.com/dart-lang/sdk/labels/needs-info | |
| [P0]: https://github.com/dart-lang/sdk/labels/P0 | |
| [P1]: https://github.com/dart-lang/sdk/labels/P1 | |
| [P2]: https://github.com/dart-lang/sdk/labels/P2 | |
| [P3]: https://github.com/dart-lang/sdk/labels/P3 | |
| [type-bug]: https://github.com/dart-lang/sdk/labels/type-bug | |
| [type-code-health]: https://github.com/dart-lang/sdk/labels/type-code-health | |
| [type-documentation]: https://github.com/dart-lang/sdk/labels/type-documentation | |
| [type-enhancement]: https://github.com/dart-lang/sdk/labels/type-enhancement | |
| [type-performance]: https://github.com/dart-lang/sdk/labels/type-performance | |
| [type-security]: https://github.com/dart-lang/sdk/labels/type-security | |
| [type-task]: https://github.com/dart-lang/sdk/labels/type-task | |
| ## Queries | |
| * [Issues with no area](https://github.com/dart-lang/sdk/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+-label%3Aarea-build+-label%3Aarea-dart2js+-label%3Aarea-dart-model+-label%3Aarea-devexp+-label%3Aarea-dev-compiler+-label%3Aarea-documentation+-label%3Aarea-front-end+-label%3Aarea-html+-label%3Aarea-infrastructure+-label%3Aarea-intellij+-label%3Aarea-js-interop+-label%3Aarea-kernel+-label%3Aarea-language+-label%3Aarea-library+-label%3Aarea-meta+-label%3Aarea-observatory+-label%3Aarea-pkg+-label%3Aarea-samples+-label%3Aarea-sdk+-label%3Aarea-spec-parser+-label%3Aarea-specification+-label%3Aarea-test+-label%3Aarea-vm) | |
| * [Issues with no priority](https://github.com/dart-lang/sdk/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+-label%3Ap0-critical+-label%3Ap1-high+-label%3Ap2-medium+-label%3Ap3-low+) | |
| * [Issues with no type](https://github.com/dart-lang/sdk/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+-label%3Atype-bug+-label%3Atype-code-health+-label%3Atype-documentation+-label%3Atype-enhancement+-label%3Atype-performance+-label%3Atype-security+-label%3Atype-task) | |
| * [Meta-issues with no assignee](https://github.com/dart-lang/sdk/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aarea-meta+no%3Aassignee) |