-
Notifications
You must be signed in to change notification settings - Fork 116
Tracking issues
The state of what's going on in the world of dart_style is tracked using issues.
Whenever possible, file issues here on GitHub and not on an internal bug tracker. Fewer inboxes makes it easier to avoid losing track of things. If you need, you can sanitize example code by replacing identifiers with equally-long fake ones.
If the formatter is crashing, please file an issue with the input that causes it to crash and a stack trace if you have one. (It should print a stack trace on failure.)
Otherwise, most formatter bugs are where it runs but produces output you don't like. The input to the formatter is combinatorial and we expect it to produce good output on almost all possible code. There's no way to validate that exhaustively, so we rely on bug reports.
A good bug report includes:
-
A complete, syntactically valid, real-world chunk of input code. You can strip out other extraneous declarations or statements that it formatted correctly, but we want a complete syntactic unit in the context where it appears. The formatter globally optimizes each statement/declaration that it formats, so we need the whole thing.
-
The output the formatter produced.
-
The output you think it should have produced, or a description which parts of the output you don't like.
If you find an existing issue and you feel confident that your case is a result of the same underlying bug, feel free to report your issue as a comment on that bug. Otherwise, it's fine to file a new issue. The formatter's rules interact in subtle ways, so it can be difficult for an end user to tell which problems are caused by the same bug. It's worth having "duplicate" issues if they give us a bigger set of test cases to work with.
Bugs not related to output quality are triaged like so:
- bug - The formatter is crashing, returning invalid data, or otherwise doing something objectively wrong.
- enhancement - A new feature, new kind of output, or API.
Most bugs are about the output, and these are triaged along a few different axes to try to give readers a sense of what the issue entails. These are rough guesses with a decent amount of subjectivity. Don't think of them as precise descriptions carved in stone. They are just scribbled notes to figure out what should and shouldn't be worked on next.
If the fix is:
- easy, it should be simple to find a solution. Once found, the solution only requires a small code change.
- difficult, it may be hard to figure out what the correct behavior should even be. Implementing it may then require sweeping or deep changes to the code.
When fixing the bug, if it is:
- safe, it has little chance of making other output worse. It is a localized improvement.
- risky, it will be difficult to improve the output in some cases without causing churn or worse output in others.
If the current output is:
- wrong, it is nonsensical, broken, or violates the style guide.
- bad, it doesn't look good to almost all readers, but is technically permitted by the style rules.
- meh, it's not intolerable, but there might be room to improve it.
If the cause of the bug is:
- known, we know why it produces that output, we just think the rules could be more sophisticated so it doesn't.
- unknown, we don't know how the rules are leading to this behavior.
If the code affected by the bug is:
- rare, most code and by extension most users will not be affected by fixing it. This means it usually applies to uncommon code constructs or only comes into play when a number of language features interact.
- common, a change can effect a large number of users and a large fraction of code, for better or worse.
Any bug may be closed and labeled as designed. This means formatter is doing what we want it to. The API is behaving correctly and the output is deliberate and desired. You may push back and say that our chosen style is wrong here, and sometimes we can change it. In most cases though, the current output is good enough that it's hard to come up with a big enough improvement to warrant disrupting existing code and users.
When a bug is fixed, it is closed without a label and is linked to the commit that fixes it. Otherwise, a comment as to why it's closed will be provided. Usually, this is someone asking the formatter do something out of its scope, like reorder or make substantive changes to code.