add paragraph about version of spec and revision of document (#26)

* add paragraph about version of spec and revision of document

* Update index.rst

Co-authored-by: David Easton <djeastonca@users.noreply.github.com>

* fix error with comment, link to format version header

* Add substitutions for central version definition

* Use release as revision date for improved PDF rendering

Co-authored-by: David Easton <djeastonca@users.noreply.github.com>
Co-authored-by: chad-earthscope <chad.trabant@earthscope.org>

conf.py

@@ -21,12 +21,20 @@
 # -- Project information -----------------------------------------------------
 
 project = 'FDSN miniSEED 3'
-copyright = '2021, International FDSN'
+copyright = '2023, International FDSN'
 author = 'FDSN'
 
-# The full version, including alpha/beta/rc tags
-release = '0.0.0'
-version = '0.0.0 DRAFT'
+version = '3'
+release = '2023-01-18 (DRAFT)'
+
+# Documentation version: major + release date
+doc_version = 'v' + version + ' rev. ' + release
+
+# Allow |doc_version| and |major_version| to be used in RST
+rst_epilog = f"""
+.. |doc_version|   replace:: {doc_version}
+.. |major_version| replace:: {version}
+"""
 
 # -- General configuration ---------------------------------------------------
 

index.rst

@@ -16,8 +16,30 @@ metadata counterpart of miniSEED is `StationXML <http://docs.fdsn.org/projects/s
 which is used to describe characteristics needed to interpret the data
 such as location, instrument response, etc.
 
+----------
+Versioning
+----------
+
+Starting with version 3 of **miniSEED**, the specification version is a single
+integer. Any non-backward compatible change to the structure of the header or
+record results in an increment to this number. The specification version
+corresponds to :ref:`field 2, Format version<field-2>`, in the
+header of records written to conform
+with this version of the specification. There are no minor revisions.
+However, the addition of new data encodings or new reserved headers is
+considered backwards compatible. The FDSN may add encodings and extra headers
+within the FDSN key or make editorial changes to the specification without change to the
+major version, resulting only in a new revision of the specification document.
+Note that all parsing software MUST allow for the potential of unknown, new data
+encodings and new extra headers as these are subject to extension. This
+requirement allows older software to parse future records successfully within
+the same specification major version, even though they may be unable to
+decompress the data payload for new encodings.
+
+This document is miniSEED |doc_version|.
+
 .. note::
-   This specification defines version 3 of miniSEED.  See
+   This specification defines miniSEED |major_version|.  See
    :ref:`background` for information on earlier versions.
 
 .. toctree::