ENH: Add a version number to serialization output.

Using semantic versioning: https://semver.org

Modifies toDict so that saved files and json requests will contain the version number.

Version number is defined in class attribute AnnotationManager.FORMAT_VERSION.

Current version is '0.1.0+2020.09.18'

Co-authored-by: Jean-Christophe Fillion-Robin <jchris.fillionr@kitware.com>

CHANGES.md

@@ -6,18 +6,22 @@ Features:
 
 * Add support for user selection of atlas through the UI at startup if no atlas is specified on the command line. See [#165](https://github.com/BICCN/cell-locator/issues/165)
 
+* Add a version number to the file format using [semantic versioning](https://semver.org/). See [#170](https://github.com/BICCN/cell-locator/issues/170)
+
 Fixes:
 
 * Fix orientation of MNI atlas. See [#163](https://github.com/BICCN/cell-locator/issues/163)
 
 * Use full annotations for MNI atlas, instead of single side annotation. See [#164](https://github.com/BICCN/cell-locator/issues/164)
 
-* Fix errors when changing interaction mode while there are no annotations in the scene.
+* Fix errors when changing interaction mode while there are no annotations in the scene. See [#173](https://github.com/BICCN/cell-locator/issues/173)
 
 Documentation:
 
 * Add [Documentation/CoordinateSystem.md](Documentation/CoordinateSystem.md) with `Updates` section.
 
+* Add versioning history to [Documentation/AnnotationFileFormat.md](Documentation/AnnotationFileFormat.md). The current version is `0.1.0+2020.09.18`
+
 ## Cell Locator 0.1.0 2020-09-18
 
 Features:

Documentation/AnnotationFileFormat.md

@@ -11,10 +11,12 @@ We mean it.
 
 # Versions
 
-## 2020-09-18
+## 0.1.0 (2020-09-18), Unversioned (2020-09-18)
 
+Annotation files generated with Cell-Locator [0.1.0-2020-09-18](https://github.com/BICCN/cell-locator/releases/tag/0.1.0-2020-09-18) do not include the `version` key.
 ```json
 {
+    "version": "0.1.0+2020.09.18",
     "markups": [
         {
             "markup": {
@@ -158,7 +160,7 @@ We mean it.
 }
 ```
 
-## 2020-08-26
+## Unversioned (2020-08-26)
 
 ```json
 {
@@ -378,7 +380,7 @@ We mean it.
 }
 ```
 
-## 2019-01-26
+## Unversioned (2019-01-26)
 
 ```json
 {
@@ -498,4 +500,3 @@ We mean it.
     "TextList_Count":0
  }
 ```
-

Modules/Scripted/Home/Home.py

@@ -273,6 +273,8 @@ def setMetadata(self, data):
 class AnnotationManager:
   """Manage serialization and bookkeeping for a collection of annotations."""
 
+  FORMAT_VERSION = '0.1.0+2020.09.18'
+
   DefaultReferenceView = 'Coronal'
   DefaultOntology = 'Structure'
   DefaultStepSize = 1
@@ -384,6 +386,7 @@ def toDict(self):
     """Convert this collection to dict representation, suitable for json serialization."""
 
     return {
+      'version': self.FORMAT_VERSION,
       'markups': [annotation.toDict() for annotation in self.annotations],
       'currentId': self.currentIdx,