GH-113: Update documentation to reflect protocol semantic versioning.

resgateio · Sep 30, 2019 · adcab35 · adcab35
1 parent 7d1d52b
commit adcab35
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 3 deletions.
diff --git a/docs/res-client-protocol.md b/docs/res-client-protocol.md
@@ -1,4 +1,6 @@
-# The RES-Client Protocol Specification v1.1
+# The RES-Client Protocol Specification
+
+*Version: [1.1.0](res-protocol-semver.md)*
 
 ## Table of contents
 - [Introduction](#introduction)

diff --git a/docs/res-protocol-semver.md b/docs/res-protocol-semver.md
@@ -0,0 +1,27 @@
+# RES Protocol semantic versioning
+
+Each protocol version is given a version number MAJOR.MINOR.PATCH, using semantic versioning with the modified meaning:
+
+### MAJOR version
+Incremented when the protocol is no longer backwards compatible. Any gateway implementation should always target the same major version. Services written for one major version will not work for a different major version.
+
+### MINOR version
+Incremented when the protocol deprecates previously valid behavior. Any gateway implementation should still handle services written for previous minor versions for a period of time (~1 year), but should 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, is provided. An example is the [RES Protocol v1.1 Update](res-protocol-v1.1-update.md) document.
+
+### PATCH version
+Incremented when backward compatible features are added to the protocol. Services written for previous patch versions 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
+
+* The current RES Protocol version is stated at the top of the [RES Protocol Specification](res-protocol.md) document.
+* The same version number is used for both the [RES Service protocol](res-service-protocol.md) and [RES Client protocol](res-client-protocol.md), even if some version changes only affect one part of the protocol.
+* Language updates, clarifications, or added examples, does not justify a version change.
diff --git a/docs/res-protocol.md b/docs/res-protocol.md
@@ -1,4 +1,6 @@
-# RES Protocol v1.1
+# RES Protocol
+
+*Version: [1.1.0](res-protocol-semver.md)*
 
 ## Table of contents
 - [Introduction](#introduction)

diff --git a/docs/res-service-protocol.md b/docs/res-service-protocol.md
@@ -1,4 +1,6 @@
-# The RES-Service Protocol Specification v1.1
+# The RES-Service Protocol Specification
+
+*Version: [1.1.0](res-protocol-semver.md)*
 
 ## Table of contents
 - [Introduction](#introduction)