Change process

Since dart format is used by most of the Dart ecosystem, evolving the style rules requires care. Small changes can often be landed, but for more impactful ones, this document contains the process we follow.

In this doc, "we" means the dart_style maintainers. "Someone" can be any Dart user, internal or external. The steps are:

1. Someone files an issue proposing a formatting change. A good issue shows real-world code with the current disliked formatting and the desired output. A really good issue shows several of these examples and describes the behavior of the preferred style rule.

2. We see if the issue looks promising. Good signals are lots of thumbs up and few thumbs down. We may hear support for it from other channels. It helps if the current formatting output is pretty unequivocally bad.

3. Someone tries to implement the new style rule. This is not always successful. In many cases it's easy to say, "Here's what I'd like this specific example to look like," without being able to articulate a general rule. Sometimes the architecture of the formatter itself precludes supporting certain kinds of rules.

4. We run the new formatter on a large corpus of Dart code. The usual corpus is a large number of recently uploaded Pub packages. Packages are not always representative of user application code, but they tend to be close enough for style evaluation. They are open source and easy to get a hold of, which is valuable.

5. We generate a diff to show how the formatted output before the change compares to the changed output. We also count how many lines of code are processed and how many lines are affected by the change.

   This shows us the real impact of the change. Ideally, the changes are clearly improvements with few regressions. In practice, given the maturity of the formatter, it's rare to make any change that doesn't make some pieces of code worse. But a good change makes most code better and the regressed code only marginally worse.

   We also look at how many lines are affected. The more lines a change affects, the more clearly better it must be to justify the churn.

6. We upload the diff somewhere so that others can see the results and link to it on the issue. We send an email to [email protected] describing the proposed change. The email links to the diff and the original issue. It requests feedback on the issue (preferably simple thumbs up or down).

7. After a week or so, if the feedback is clearly positive relative to the scale of the change, we land it. Otherwise, we close the issue with an explanation. Note that scale is important. Since churn itself has a real user cost, the larger the impact of the change, the more clearly positive it must be. A change that touches 10% of the lines of existing Dart code but is only favored by 53% of the users isn't a win. We're looking for changes that are either targeted or beloved.

At any point, we may decide that a change isn't going to work out and decide to not do it. If a proposed change makes it through all of the steps, then we've got a winner and the formatter gets better in a way that most users like.