RES Protocol semantic versioning
Closed this issue · 1 comments
Issue
As new additions are made to the RES protocol, it is needed that developers understand the impact these changes may have on their existing services.
This can be resolved by adhering to semantic version for the protocol. However, since a protocol does not need "bug patches" in the same sense as software, the meaning of each level will be slightly different.
Given a version number MAJOR.MINOR.PATCH (eg. v1.1.5):
MAJOR version
Incremented when the protocol is no longer backwards compatible. The current Resgate repository will always target the v1 protocol. In case of a new major version, a new "Resgate2" repository would be created, and should be considered a different project. Services written for v1 would not work for v2.
There are no plans for any MAJOR version changes.
MINOR version
Incremented when the protocol changes deprecates previously valid behavior. Resgate would still handle services written for previous version for a period of time (~1 year), but will log warnings in case legacy behavior is detected.
During the deprecation period, service developers need to upgrade their services. A document describing these changes, and how to upgrade a service, will be provided. An example is the RES Protocol v1.1 Update document.
There are no planned features that would require any MINOR version change.
PATCH version
Incremented when backward compatible features are added to the protocol. Services written for previous version will continue to work without modifications.
New patch versions may include features like:
- New optional error codes
- New resource types
- New resource events
- New optional event properties
- New optional response properties
Notes
- A single RES Protocol version will be used for both the Service and Client protocol, even if some version changes only affect one part of the protocol.
- The current RES Protocol version should be stated at the top of the RES Protocol Specification document, for each new release.
- Language updates, clarifications, or added examples, will not require a version change.