Current use of semver not applicable to prettier

[reinseth]

First off, thanks for a great library and fantastic effort for the community.

This is a suggestion about the versioning scheme used by prettier.

I would argue that using the minor version of semver for changes isn't applicable to prettier. Why? Any changes that leads to different formatting isn't really compatible with the previous version. For instance, if package.json specifies ^1.2.2 (where a caret version is the default when installing with npm), one repo user could still be at 1.2.2 and another repo user could be at 1.4.4, and they would have different formatting applied the sources leading to an inconsistent style across the project (and following commit wars until the version difference is resolved).

A workaround would be to use a tilde (~) version in package.json to only allow automatic patch upgrades, but since this is not the default behaviour of npm it will probably lead to problems for many people who are not aware of the issue.

My suggestion is to always increment the major version whenever a change that leads to different formatting is applied.

[azz]

My suggestion is to always increment the major version whenever a change that leads to different formatting is applied.

That would mean every release would be a major version.

If prettier produces a different output on two different versions, that's not a breaking change. Ideally prettier will never have any breaking changes, but if there are, it would be to the the API/CLI itself, not the output.

[SimenB]

With npm@5 defaulting to creating lock files (and yarn which have done it for a while) different versions on different machines shouldn't be a huge issue anymore, even with ^ (or even *).

[vjeux]

The fact that npm by default automatically upgrades you to a version in the future is completely broken in my opinion and why I'm so glad that yarn came up with a lockfile and now npm 5 does as well.

I also don't believe in semver in the context of JavaScript ecosystem. I've been broken so many times by a deep dependency that happens to bump a patch version with a breaking change, coupled with the automatic update behavior above.

In my view, every bump version can have a breaking change. The major, minor and patch can be used as marketing.

We initially used 0.0.x and shipped frenetically in the beginnings. Then 0.x.0 when it stopped being a toy project and we could see it being used by real people. We used 1.0 to signify that prettier was ready to be used at large scale. Then 1.x in order to show big milestones like typescript and css support. And 1.x.y for "hot fixes" after a release.

I don't have any intention of doing 1.0.0, 2.0.0... everytime we do a release, I'm sorry.

[vjeux]

I'm going to close this as we're not looking into changing the way we number releases. Thanks for raising the issue in the first place!

[reinseth]

If prettier produces a different output on two different versions, that's not a breaking change.

@azz: Prettier is a function that takes source code as input and produces formatted source code as output. Given the same input, the same output is always produced. If two different versions produces different output given the same input, then there's a breaking change between these two versions.

@SimenB: Thanks for the input. Lockfiles do indeed mitigate this problem, but for the time being many projects are not using npm5 or yarn.

@vjeux: I can live with your decision, but considering that Prettier has the intention of becoming the de facto formatting tool, I think it's a shame that it doesn't adhere to the de facto versioning system in the industry, and instead changing the semantics of the same system to its own purpose. At least it would be nice if this was mentioned in the docs.

[felixfbecker]

So, what is the current version policy? Sentimental versioning 😄 ? It would be nice to at least know if patch releases are guaranteed to never cause a change in formatting so it's possible to use ~, or if not, please explain the versioning policy in the README as npm packages are usually expected to follow semver.

What is the problem with upping major version numbers?

[azz]

Because almost every PR changes the formatting slightly, which means every release would be major, no minors or patches.

I don't think it makes sense to bump major for formatting changes. The API is that prettier.format(string) returns a string. If that contract changes, that would be a breaking change, and it would make sense on that occasion to bump the major version.

If Prettier was to overhaul the CLI, remove an option, or change the API itself, those would all be breaking changes.

[CGamesPlay]

I was just searching around to find if Prettier had defined an actual policy around its use of semver and a bit sad to see that it's been rejected.

Whatever the actual policy on semver with prettier is, I wish that the maintainers could answer these questions for me:

• What is the semver change when previously formatted code is formatted differently?
• What is the semver change when previously rejected code is now formatted? For example, if pattern matching were to be supported.
• What is the semver change when previously formatted code is now rejected? For example, if a bug were discovered in the parser that allowed it to be too permissive.

Obviously, there's also API questions pertaining to semver, but those are more obvious according to the official semver guidelines.

[lydell]

In a way, the API of Prettier is “string in, string out” without saying much about what those strings look like. So in theory we can do any changes we like and release them as patch releases as long as the string -> string contract is preserved. But of course we don’t do that since it wouldn’t be very nice to users :)

What is the semver change when previously formatted code is formatted differently?

Any. Depends on the case. The more impact, the more bump. Technically, you could say that any change whatsoever is a breaking change. But only doing major releases won’t help anyone. And it would mask actual API breaking changes. This is also why it can make sense to think of the API more of like string -> string where the strings are black boxes like I mentioned above.

What is the semver change when previously rejected code is now formatted?

Most likely minor. (New feature.)

What is the semver change when previously formatted code is now rejected?

This is a tough one. We have this problem for decorators (#2630). There was a similar situation with GraphQL (#4012), where we ended up parsing both old and new syntax but only outputting the new.

For example, if a bug were discovered in the parser that allowed it to be too permissive.

That could likely be a patch release.

---

In summary, the above is how I have understood how things work so far. Basically, Prettier is a hard thing to version. Which is why we recommend pinning the version in package.json. We try to use our best judgement to make the experience smooth for the majority of people.

[azz]

Put simply: Don't rely on semver for this module, as it doesn't fit that model. Always pin an exact version in package.json.