Model-viewer: Discuss (and document) deprecation cycle

[smalls]

We've had a few recent issues where we want to change attributes (#452 and #429). In #452 we changed the attribute name, in #429 (at least currently) we may preserve the old attribute for a period of time.

Ideally, expectations around when we'll deprecate attributes, and how long a deprecated attribute will survive for would be documented.

However, before we can document this, I'm interested in what cycles we'd all be comfortable with or would prefer.

[mikkoh]

Is a true deprecation cycle something you'd want to do after 1.0.0? Cause likely at that you'd want to bump major version on all breaking changes.

[smalls]

I think 1.0.0 will be a good time to do that - 1.0.0 (at least imho) brings with an expectation of more stability, and documented (and followed) deprecation cycles are a part of that stability.

We're not there yet, though (as I write this 0.0.2 just released). I think some of the value we can get out of this pre-1.0 time is to iterate on our attribute names and APIs?

[mikkoh]

Might be good to start to increment minor on breaking changes while still in 0.y.z. At least gives some feeling of stability. I feel like I read that this is standard pre-release but I could be wrong.

[smalls]

No, I agree - incrementing the minor version for a breaking change even in pre-release seems correct. I don't want to leave a deprecated attribute in until 1.0.0 (or even 2.0.0), which we might decide to do after we hit 1.0.0.

[cdata]

And in fact we incremented minor on a breaking change today FWIW 😄

[cdata]

My rule of thumb has been that the right-most non-zero number is effectively your major version as far as releasing breaking changes is concerned.

So, the following increments are all allowed to contain breaking changes:

• v0.0.1 => v0.0.2
• v0.1.x => v0.2.0
• v1.x.y => v2.0.0

For new features, I like to bump the minor version. The following are all valid increments to incorporate new features in a release:

• v0.0.1 => v0.0.2
• v0.1.0 => v0.1.1
• v1.0.x => v1.2.0

And for releases that only include bugfixes / chores, a patch release is usually suitable:

• v0.0.1 => v0.0.2
• v0.1.0 => v0.1.1
• v1.x.0 => v1.x.1

[elalish]

@cdata This documentation is part of 1.0, right?

[cdata]

I originally left it out, but it would be a cheap win so let's do it