BC-Promise / Upgrade section in Docs

[HellPat]

@reinink I like that sentence you wrote in #84

This is breaking change, and shouldn't be merged in until the next breaking release.

Since atm this is alpha software I wasn't sure if there is something like a BC promise.
Seems you plan to comply to SEMVER? Even for Alpha, or is 1.0.0 the next BC-Break?

Maybe we should document a "Update"-Chapter where the update-process for tailwind is described. There would be place to explain the difference ^1.0.0 vs ~1.0.0 and the impact on the project.

e.g. if you use ^1.0.0 filesize of a newer version could increase with yarn upgrade.

Many users are be that experienced, so a little explanation and a link to https://docs.npmjs.com/getting-started/semantic-versioning could be nice.

Also there is a place for writing down the BC-promise.

[adamwathan]

Yeah the plan for pre-1.0 is to treat minor releases as breaking, so 0.2.0 can have breaking changes but 0.1.x won't.

We discussed it a bit internally and are going to stop calling it "alpha" explicitly at this point, because I think it sends the wrong message. It's pre-1.0 so there will be lots of rapid development and things can change and break, but it's not alpha in any special way that any other pre-1.0 software is.

This section of the SemVer FAQ is inline with how we are thinking of pre-1.0:

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

Doesn’t this discourage rapid development and fast iteration?

Major version zero is all about rapid development. If you’re changing the API every day you should either still be in version 0.y.z or on a separate development branch working on the next major version.

We don't have an exact timeframe in mind for 1.0, but in my mind it's a short-term goal; but we don't plan to stay in 0.y.z for years and years like has happened with other libraries.

Once we actually release an 0.2.0, we'll make sure to add documentation about upgrading and the update policy 👍

[HellPat]

Thanks for clarification, this is good to hear.
You can close this issue if you want or keep it as a reminder, or add your statement to the current docs (I'm quite sure I'm not the only one thinking about that)

[adamwathan]

We’re working on an FAQ section in the docs to address a variety of topics like this in a quick way until we have dedicated documentation for those topics, so I’ve made a note to talk about this there for now 👍🏻