RFC: Experimental/Deprecated flags for major formatting changes

[sosukesuzuki]

Motivation

Prettier is already a mature tool, but occasionally there are requests for major formatting changes.

As the Prettier team, we would like to adopt these changes if they are good.

However, releasing them suddenly would create friction with most of the current Prettier users.

This RFC proposes a feature to incorporate major formatting changes while minimizing friction with users.

Overview

We add two new types of options called experimental flags and deprecated flags.

These flags exist for a different reason than the existing options, so do not violate Prettier’s Option Philosophy.

For example, consider a major formatting change such as “adding 4 spaces after the if statement” (we would never actually do this, but it serves as an example).

When this new hypothetical format is applied, code like this:

if (cond) {
}

gets formatted as this:

if    (cond) {
}

Releasing such a significant format change without proper communication and testing would cause friction with users.

So when releasing a minor version, we announce an option like --experimental-if-4-spaces and apply the above major formatting change only when this option is enabled.

After that, we obtain feedback from users in some way (we need to consider how to obtain feedback from users).

Based on the feedback from users, we decide whether or not to officially adopt this major formatting change (we need to consider how to make the decision, such as by voting).

During this process, we may choose to change the behaviour of the experimental flag and release this change in a new minor or patch version.

Suppose, for example, that --experimental-if-4-spaces is decided to be officially adopted.

In that case, when releasing a major version, we remove --experimental-if-4-spaces and make the corresponding major formatting change enabled by default.

Together with removing the experimental flag, we add a new option named --deprecated-if-spaces and apply the legacy format only when this option is enabled.

A few months later, we remove the --deprecated-if-spaces flag.

After this, the original format can no longer be applied.

Both --experimental--* and --deprecated-if-spaces are temporary options and are are not subject to semantic versioning.

The only purpose of the deprecated flag is to allow users to chose a convenient moment in time to migrate to the new format.

We are not planning to retain such flags as permanent options as this would violate the Option Philosophy.

Thanks

This idea was originally proposed by @kachkaev.

[fisker]

If #3806 and #13183 will add under experimental flags, they won't be breaking changes, don't have to be included in v3.

Should we start release v3?

[sosukesuzuki]

If #3806 and #13183 will add under experimental flags, they won't be breaking changes, don't have to be included in v3.

Indeed, you are right. Once the Release blog and VSCode extension are ready, we can start release v3.