From 20fa73dfa2a70bcbd1dd24c58a2ab29ac9bf28b7 Mon Sep 17 00:00:00 2001 From: Neil Clifford Date: Thu, 5 Oct 2017 16:49:03 +0100 Subject: [PATCH] Full proof read and edit --- docs/archived/CM_Compatibility.adoc | 77 ----------------------------- docs/archived/CM_Versioning.adoc | 69 -------------------------- 2 files changed, 146 deletions(-) delete mode 100755 docs/archived/CM_Compatibility.adoc delete mode 100755 docs/archived/CM_Versioning.adoc diff --git a/docs/archived/CM_Compatibility.adoc b/docs/archived/CM_Compatibility.adoc deleted file mode 100755 index 9c28f7b90..000000000 --- a/docs/archived/CM_Compatibility.adoc +++ /dev/null @@ -1,77 +0,0 @@ -= Chronicle Map Compatibility -Neil Clifford -:toc: macro -:toclevels: 1 -:css-signature: demo -:toc-placement: macro -:icons: font - -toc::[] - -== Java Implementation Compatibility - -=== Public API - -The *public API* comprises public classes that are included in -http://www.javadoc.io/doc/net.openhft/chronicle-map/[Javadoc]. - -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/archived/CM_Versioning.adoc b/docs/archived/CM_Versioning.adoc deleted file mode 100755 index 16f14bd89..000000000 --- a/docs/archived/CM_Versioning.adoc +++ /dev/null @@ -1,69 +0,0 @@ -= 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.14.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>>