Indicate stability

[ForbesLindesay]

I think we should add an indication of stability to the website. I think this specific spec is pretty stable (or rather will be once 1.1 is ratified in #84) and it would be really good to indicate that.

[domenic]

What kind of indication do you think would be helpful? I guess I've always thought of specs as somewhat stable things inherently, although now that you mention it, the distinction between the various W3C spec stages (editor's draft, candidate recommendation, recommendation, etc.) does kind of give this.

[briancavalier]

@ForbesLindesay do you have some simple examples of what you're thinking here? Are you thinking we should somehow indicate that the version of the spec that someone sees when they land on the repo README vs. the one deployed via github pages may be different? Or something else?

[ForbesLindesay]

I think it would be nice to indicate that the version in the readme is not always stable. I was more thinking that we should indicate on the web-page version that then is extremely stable and that backwards incompatible changes will only be made with an extremely good reason, and most likely won't be made at all.

[briancavalier]

Yeah, I think it's a good idea to indicate that master README isn't necessarily the officially released version, and that people should look at github pages. If we can handle/phrase that in a way that allows us not to have to re-edit the spec every time we push to github pages, that would be ideal!

To some degree, semantic versioning implies the stability of then, and the spec overall. But maybe that's not quite strong enough, and we should say something stronger about then, as @ForbesLindesay suggested. What do others think?

[ForbesLindesay]

My impression is that although we all know it's really stable, and that it's made by people who understand how semver works, many other people might not.

[domenic]

At this point I think we want a concrete idea of what such text would look like :). My first idea is to add a very short sentence in the intro text per #106. Or, we could relegate it to a sub-page like the change log. (Note that sub-pages will get a lot more prominence in my redesign of gh-pages for 1.1, since we need to link to differences from Promises/A, change log, and implementations at the very least.)

[ForbesLindesay]

A first stab at such text:

"The then method described in this specification is considered very stable. Backwards incompatible changes will be avoided unless essential either to fix an important corner case or to match current defacto behavior of libraries. Such changes would be indicated by incrementing the major version number."

It feels a bit long, but I wanted something that's hopefully easy to understand without any specific background knowledge.