Document change process in contributing guidance

[QuintinWillison]

Closely relates to ably/features#12, so I'll not duplicate the content from the opening commentary on that issue here, to save myself time.

However... for this repository, the following are also very important...

Guidance on Semantic Versioning

SemVer is deliciously clear around definition of terms like 'incompatible API change' and 'backwards compatible'.

What we need to be clear on in our guidance is from what perspective to apply those definitions to. We have a general principle / requirement that our service 'makes right' in order to keep supporting older SDK versions, where those older SDKs will be behaving differently (e.g. protocol difference). Therefore, if the protocol changes in such a way that the SDK needs to communicate with the service in a different way in order to do the same (or similar) thing to what it was doing previously, do we define that as a 'incompatible API change'? From whose eyes is/can the term API to be understood in the context of the features spec that lives in this repository?

These questions need to be answered when working on this issue.

Guidance on Spec Point Add/Delete/Mutate

Should start by moving Ably SDK Team: Features Specification from the ably/engineering repository to this repository.

Must add guidance around spec point mutation. Specifically that patch updates to the spec can correct mistakes in spec points but, otherwise, spec points should not be mutated between versions in a way that fundamentally changes the implications for client library SDK implementations. We do not version the spec points individually, just the spec as an atomic whole. That means that once an SDK has declared conformance with a spec point then that remains a valid assertion for as long as that spec point exists. If a spec point needs to materially change (e.g. scope expanded or modified behaviour) then that needs to become a new spec point, with the old spec point 'deleted'.

An example of a spec point where scope was expanded during the lifetime of version 1.2.0 of the specification is TM2i in ably/docs#1444. Some SDKs implemented TM2i before the ref field was added to message.extras and, therefore, there's no logical way for us to track which SDKs have 'fully' adopted it. Being stricter around spec point mutation in future will prevent this sort of confusion from arising again.

[sync-by-unito]

➤ Automation for Jira commented:

The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-2804

[QuintinWillison]

This should have been closed as completed in #120.