From c190bbbf09ec2e3592aa7cd917db6609e017d4e0 Mon Sep 17 00:00:00 2001 From: Neil Clifford Date: Fri, 29 Sep 2017 14:30:03 +0100 Subject: [PATCH] Initial re-work of documentation --- docs/CM_Compatibility.adoc | 77 ++++++++++++++++++++++++++++++++++++++ docs/CM_Versioning.adoc | 69 ++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100755 docs/CM_Compatibility.adoc create mode 100755 docs/CM_Versioning.adoc diff --git a/docs/CM_Compatibility.adoc b/docs/CM_Compatibility.adoc new file mode 100755 index 000000000..1aea97947 --- /dev/null +++ b/docs/CM_Compatibility.adoc @@ -0,0 +1,77 @@ += Chronicle Map 3 Compatibility +Neil Clifford +:toc: macro +:toclevels: 1 +:css-signature: demo +:toc-placement: macro +:icons: font + +toc::[] + +== Java Implementation Compatibility + +=== Public API + +For Chronicle Map, the *public API* is comprised of public classes that are included in [Javadoc]( +http://www.javadoc.io/doc/net.openhft/chronicle-map/). + +Note: Other public classes are not subject to +the following rules; they may be changed in any way, or even removed. + + - Class and method names, types and number of parameters in already existing methods shouldn't be + changed. + - Any methods could be added to the classes and interfaces that are not subject for + subclassing or implementing by the library users, such as `ChronicleMap`, `ChronicleMapBuilder`, + `MapEntry`, but in a way that any existing code calling methods on those classes still compile, not + break due to ambiguity in method resolution. + - Only non-abstract (concrete or default) methods could be added to the classes and interfaces that + are subject for subclassing by the library users, such as `MapMethods`, `MapEntryOperations`, + `SizedReader`. + +=== Behaviour + +Semantics and actual effects of API calls might change between Chronicle Map versions with +[different `` number](versioning.md), e. g. default serialization forms of key or value objects +of some types could change, "high level" configurations in `ChronicleMapBuilder` could produce +Chronicle Maps with different "low level" configurations, etc. Such changes should be documented in the release notes. + +=== Persistence File Binary Form + +A persisted Chronicle Map store (a binary file), produced by a production release of the library, +should be accessible and updatable by any subsequent production release of the library in 3.x +branch, unless the older version has bugs that lead to data corruption. + +To support this: + + - Serialization forms of any classes shouldn't be changed. When e. g. a marshaller class (say, + `StringBytesReader`) of objects of some type is changed, and it's serialization form should be + changed, a new class called `StringBytesReader_3_5` (5 is the `` number of the version of the + library, in which this change is made) should be created and put along with older class. + + - When the specification revision is updated (hence binary form could be completely changed), a + new version of root implementation class, e. g. `VanillaChronicleMap_3_5` should be created and + put along with older version, which should keep behave the same as before. + +=== Replication Protocol + +The replication protocol might change between Chronicle Map versions with different `` number. +Chronicle Map nodes running different versions of the library should not communicate to each other. +This may lead to failures, but not to data corruption on either of the nodes. + +== Specification Compatibility + +The Chronicle Map Data Store Specification could be updated without changing the revision while it +remains backward compatible, i. e. the implementation of the newer version of the specification +could access and update any persisted Chronicle Map store, produced by an older version. +In addition, potential *concurrent* accessing implementations of older versions ("within" the same +revision) shouldn't lose correctness and corrupt the data. + +If more substantial changes to the specification are required, the revision number should be +updated. + +The binary form of Chronicle Map and algorithms could change between revisions to any degree, but +[guarantees](../spec/1-design-goals.md#guarantees) provided by the specification shouldn't be +weaken. + +''' +<<../ReadMe.adoc#,Back to ReadMe>> diff --git a/docs/CM_Versioning.adoc b/docs/CM_Versioning.adoc new file mode 100755 index 000000000..a34739a54 --- /dev/null +++ b/docs/CM_Versioning.adoc @@ -0,0 +1,69 @@ += Chronicle Map 3 Versioning +Neil Clifford +:toc: macro +:toclevels: 1 +:css-signature: demo +:toc-placement: macro +:icons: font + +toc::[] + +== Java implementation Versioning + +The versioning format is as follows: + +`..` + +For example: +`3.1.1` + + +=== The number should be updated, when: + + - a feature, or public API method is added. + + - the behaviour of `ChronicleMap`, `ChronicleMapBuilder` or any other class or method or subsystem + is semantically changed. + For example, when configuration heuristics in `ChronicleMapBuilder` are improved, and + `ChronicleMapBuilder` configured the same way constructs a `ChronicleMap` with a different + number of segments, or segment's capacity, etc. + + - any dependency is updated, even if only `` number is updated, e. g. `chronicle-bytes` + dependency is updated from `1.1.1` to `1.1.2`. This rule doesn't apply to dependencies to the umbrella POMs which merely determine versions of other dependencies (namely `chronicle-bom` and + `third-party-bom`), if the versions of actual dependencies don't change between those versions of umbrella POMs. Also, this rule doesn't apply to dependencies with Maven scopes of `test` or `provided`. + + - bug fixes, performance optimization or feature addition requires to change the binary or + serialized form of Chronicle Map data store (therefore revise the Chronicle Map data store + specification, see below), or the binary replication protocol, or the serialized form of some + marshaller classes, that requires to [create new versions of classes](compatibility.md). + +=== The number should not be updated, i. e. the next release could update only the "patch" number, when +: + - A bug fixed, in a way that doesn't make any working code to change its behaviour semantically. + - Performance optimized: some working code changes its performance characteristics, + but not semantics + +During development after the release of the version `3.y.z` the library should be versioned +`3.y.-SNAPSHOT`. As soon as changes made are substantial enough for the next released version +to update the "minor" number, the version should be changed to `3..0-SNAPSHOT`, *in the same +commit* these changes are made. + +Suffixes `-alpha`, `-beta`, `-rc` etc. mean this is a pre-production release. + +== Specification Versioning + +The first Chronicle Map 3 production release designates the Chronicle Map data store specification, revision 1. + +When the specification should be updated in a way that is not [backward compatible](compatibility.md#the-specification-compatibility), the revision should be updated (revision 2, 3, ...) and the Java implementation of this revision should have '' number updated in its +version. + +During the development after the release of the revision `x`, while the specification is backward +compatible, it should remain versioned `x`. In the same commit where the specification becomes +incompatible, its revision should be set to `-pre` until the next production release. + +Releases and updates to the `` number in the library version should be synchronized with +updates to the specification revision number. + + +''' +<<../ReadMe.adoc#,Back to ReadMe>>