Add versioning policy text to introduction

Closes #3
cchdo · Mar 27, 2024 · 8046f3f · 8046f3f
1 parent 21e3942
commit 8046f3f
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 3 deletions.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,5 +1,10 @@
 Changelog
 =========
+2024-??-?? (1.2.2)
+------------------
+* Added versioning policy to introduction.
+* Added parameter database version to the params page.
+
 2024-03-22 (1.2.1)
 ------------------
 Update CCHDO Params to 2024.3

diff --git a/docs/gen_paramters_doc.py b/docs/gen_paramters_doc.py
@@ -1,7 +1,7 @@
 import json
 import itertools
 from textwrap import indent, dedent
-from cchdo.params import WHPNames
+from cchdo.params import WHPNames, __version__ as params_version
 
 flag_refs = {
     "woce_ctd": ":ref:`CTD Quality Codes`",
@@ -78,7 +78,7 @@ def gen_cf_table(param):
 
 
 with open('_autogen_paramlist', 'w') as f:
-    f.write('''
+    f.write(f'''
 .. _parameters-list:
 
 Parameters
@@ -89,6 +89,8 @@ def gen_cf_table(param):
 :download:`validation schema <parameters.schema.json>` for the
 parameters json.
 
+CCHDO Parameter database version: {params_version}.
+
 .. hlist::
   :columns: 3
 

diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -74,4 +74,14 @@ Unicode Representation in this Document
 Character in this document will be defined as unicode points in the format U+#### where the # symbols are hexadecimal numbers.
 Since exchange files are defined to be UTF-8 encoded, this unambiguously specifies the exact bits which must occur in a file.
 
-.. [#f1] As of May 2020, 95.0% of the text on the internet is encoded with UTF-8.
+.. [#f1] As of March 2024, 98.2%% of the text on the internet is encoded with UTF-8. https://w3techs.com/technologies/overview/character_encoding
+
+Versioning
+----------
+The format spec follows semantic versioning ``x.y.z`` where:
+
+* ``x`` is the major version number, incrementing this number would be due to breaking changes to the exchange format spec, we do not expect this to happen ever.
+* ``y`` is the minor version number and would indicate "non-breaking" changes to the specification, examples of non-breaking changes could include clarifications, the addition of new synthesized parameters (like _FLAG_W).
+* ``z`` is the release number and would be incremented for things such as grammar changes, spelling corrections, and updating the parameters list, the parameters list is versioned independently.
+
+The components of the numbers are incremented independently, e.g. the version after ``1.0.9`` would be ``1.0.10``.