docs: define versioning policy

[mattsb42-aws]

Issue #, if available:

resolves: #104

Description of changes:

This refines our versioning policy and explains how it applies to specification documents and implementations.

NOTE: This includes a change to fully adopt Semantic Versioning. This changes the requirements for MINOR versions.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[acioc]

This wording is a bit confusing. So known implementations just refers to each ESDK language, correct? So we don't expect to have the matrix contain a history of ESDK releases per language along with what specification version that release used, right (e.g. we will not have Python release A.B.C implements spec version X.Y.Z for each release of the ESDK for Python - we will not have multiple lines for Python on the implementation table)?

the implementation version that first implemented that specification version is a bit weird. I guess I don't really understand the difference between confirmed and minimum (specifically because minimum is bigger than confirmed in this case, and confirmed vs minimum represent a major version change, so they shouldn't be compatible with one another).

I think it might make more sense to potentially combine the "Minimum Version Confirmed" with the Language or similar (to make it clearer that one version is about the ESDK implementation and the other is just the spec that it uses).

I think my big worry here is that this is the kind of info we should track in an ESDK README - so someone looking at the implementation knows right away what it does. If we want to track it here as well, we should make it very obvious in the ESDK READMEs how to get that information. We definitely shouldn't track it twice or someone will forget to update one and not the other. This also means that, whenever an ESDK releases, someone needs to update all correct spec pages to the latest version.

[mattsb42-aws]

My intention is that there are two versions that are important: the version of the spec doc that an implementation implements, and the earliest version of the implementation where we have verified that it correctly implements that spec doc version. I'm trying to avoid having to update the spec doc every time an implementation changes and vice versa.

I agree that each implementation should define what version of the spec it implements. I was thinking that it might also be useful to have a single point of reference for what implementations implement what version of each spec doc, so that we have somewhere to look at a glance to see if any are divergent, but that should ideally always be an ephemeral thing.

Another option would be to say that each spec doc MUST link to each known implementation and that implementation MUST state what version of the spec doc it implements. The reason I don't love this option is because it leaves us in a state where we will inevitably end up with a spec doc saying that an implementation implements it, when that is not in fact true (implementation lags spec or spec lags implementation).

Maybe split the difference and link the implementation with a "last confirmed compatible with spec version X.Y.Z" but not mention what version of the implementation that was?

[acioc]

I'm trying to avoid having to update the spec doc every time an implementation changes and vice versa.

That's fair. I think it might be reasonable to have the implementation linked in the relevant classes though? So if I make an implementation code change as a result of the spec, I can have my implementation change include a header (or something) that links to the spec version it's updating to? That way, we don't have to update the spec every time an implementation changes.

I agree that each implementation should define what version of the spec it implements. I was thinking that it might also be useful to have a single point of reference for what implementations implement what version of each spec doc, so that we have somewhere to look at a glance to see if any are divergent

I do agree with this. But we would still need to check every spec page to see what is/ isn't divergent, which isn't that much quicker than having each spec page link to the implementation, and having the implementation tell us the spec version it is using.

implementation lags spec or spec lags implementation

Totally agree. I don't think that's super scalable and, inevitably, someone will forget to update something

split the difference and link the implementation with a "last confirmed compatible with spec version X.Y.Z" but not mention what version of the implementation that was

That might be fine. I think I personally still prefer having the spec link to the page where it's implemented (example: once we have a spec doc for a keyring, and that keyring is implemented, its location is pretty unlikely to change), but have the implementation itself say what version of the spec it's implemented. This way, it at least gets us in a rhythm of committing implementation code that directly says 'this change is being done to update this to X.Y.Z spec version).

Overall, I really think we need to make sure our implementations are updated to reference the spec when those changes are made. That'll make it clear to our customers why the change occurred, what version of the spec they should expect it to follow, and makes it easier for PR reviewers to compare implementation to the spec as well.

[acioc]

I agree with the new text.

We should definitely establish the way of having the implementation refer to the correct spec version too. This is prob a bit different than #128 (which I read as "how do we ensure the correctness of the implementation") as opposed to "how do we ensure our customers (and we) know what the implementation is supposed to to be implementing (aka documentation)