mirror of
https://github.com/OpenHFT/Chronicle-Map.git
synced 2021-09-13 01:26:12 +00:00
Full proof read and edit
This commit is contained in:
Neil Clifford
@@ -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 `<minor>` 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 `<minor>` 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 `<minor>` 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>>
|
||||
@@ -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:
|
||||
|
||||
`<major>.<minor>.<patch>`
|
||||
|
||||
For example:
|
||||
`3.14.1`
|
||||
|
||||
|
||||
=== The <minor> 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 `<patch>` 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 <minor> 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.<x+1>-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.<y+1>.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 '<minor>' 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 `<x+1>-pre` until the next production release.
|
||||
|
||||
Releases and updates to the `<minor>` number in the library version should be synchronized with
|
||||
updates to the specification revision number.
|
||||
|
||||
|
||||
'''
|
||||
<<../ReadMe.adoc#,Back to ReadMe>>
|
||||
Reference in New Issue
Block a user