Parker Lougheed
8716461eaf
Fixes a few minor issues relating to outdated links, spelling, Markdown formatting, word choice, etc. Bug: https://github.com/dart-lang/sdk/issues/54066 Change-Id: Ic7b9b33b27d2ce2c30f9b1fe17b0bc91873ecfb7 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/369764 Reviewed-by: Nate Bosch <nbosch@google.com> Reviewed-by: Devon Carew <devoncarew@google.com> Commit-Queue: Devon Carew <devoncarew@google.com>
323 lines
17 KiB
Markdown
323 lines
17 KiB
Markdown
> [!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, "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.
|
|
|
|
### 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-analyzer-cfe+-label%3Aarea-analyzer+-label%3Aarea-build+-label%3Aarea-dart2js+-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)
|