Update documentation (#24)

* Describe versioning in general

* Fix up READMEs for the code packages

* Specify files for documentation label

.github/release-drafter-java.yml

@@ -34,8 +34,10 @@ categories:
 
 autolabeler:
   - label: 'documentation'
-    branch:
-      - '/docs{0,1}\/.+/'
+    files:
+      - 'README.md'
+      - 'generated/java/datadoc-model/README.md'
+      - 'generated/python/datadoc_model/README.md'
   - label: 'bug'
     branch:
       - '/fix\/.+/'

.github/release-drafter-python.yml

@@ -34,8 +34,10 @@ categories:
 
 autolabeler:
   - label: 'documentation'
-    branch:
-      - '/docs{0,1}\/.+/'
+    files:
+      - 'README.md'
+      - 'generated/java/datadoc-model/README.md'
+      - 'generated/python/datadoc_model/README.md'
   - label: 'bug'
     branch:
       - '/fix\/.+/'

README.md

@@ -4,19 +4,61 @@ Data Model for use in Statistics Norway's Metadata system
 
 ## Purpose
 
-This package contains pydantic models defining the fields and data types used in Statistics Norway's metadata system. The purpose of these models is to:
+This package contains models defining the fields and data types used in Statistics Norway's metadata system. The purpose of these models is to:
 
 - Enable validation of user data
 - Enable serialization and deserialization of metadata files
 - Support versioning of the metadata format
 - Enforce consistency across multiple tools
 
-## Single Source of Truth
+## Model definition
 
-Fields and data types defined in models in this package are specified on internal Statistics Norway wiki pages:
-
-- <https://statistics-norway.atlassian.net/l/cp/kQ9rpshS>
+The models are defined as [JSON Schema](https://json-schema.org/) documents. These are the single source of truth for metadata formats at Statistics Norway. The models reside within the `src/` directory in this repo. They may be directly used to validate metadata documents.
 
 ## Code generation
 
-The models are defined as [JSON Schema](https://json-schema.org/) documents. These reside within the `src/` directory in this repo. Code for a range of languages is generated from the JSON Schema and will live inside the `generated/` directory, with a subdirectory for each language.
+In order to facilitate production of compatible metadata documents, we generate code in a variety of languages. All languages use the models defined in the `src/` directory as their source. The generated code lives in the `generated/` directory, with a subdirectory for each language, and the package within a further subdirectory.
+
+Currently supported languages are:
+
+- Python
+- Java
+
+## Versioning
+
+There are many versions in this repo, and care must be taken when incrementing versions such that we maintain a consistent approach and so we may maintain backwards compatibility for all existing metadata documents.
+
+### Overall strategy
+
+All versions in this repo follow semantic versioning.
+
+### JSON Schema versions
+
+_All_ changes to JSON Schema documents must result in version increments.
+
+#### Patch versions
+
+The most minor changes, such as corrections to descriptions of fields should result in patch version increments e.g. 0.0.1 -> 0.0.2.
+
+#### Major versions
+
+Due to the strict nature of these models, it is very easy to introduce breaking changes. All breaking changes should result in major version increments e.g. 1.1.14 -> 2.0.0. Examples of changes which are breaking:
+
+- Removing a field
+- Adding a field
+- Changing the name of a field
+- Changing the type of a field (unless it makes the type more _permissive_)
+
+#### Recording the version
+
+Each document has a field `document_version` which is a constant and records the version of the document when it was created. This should be incremented in the JSON Schema when changes to that schema are made.
+
+### Code package versions
+
+The code package versions should be incremented _at least_ as much as JSON Schema increments. For example, a minor version increment in a JSON Schema means all code packages should be incremented by a minor version. The only exception to this is if there are other technical changes which can be breaking, then the major version should be incremented.
+
+More detail is provided in the README for each package.
+
+## Release process
+
+Each language has its own release process, refer to the READMEs with the 'generated/' directory.

generated/java/datadoc-model/README.md

@@ -0,0 +1,18 @@
+# ssb-datadoc-model
+
+Data Model for use in Statistics Norway's Metadata system
+
+## Purpose
+
+This package contains Java classes defining the fields and data types used in Statistics Norway's metadata system. The purpose of these models is to:
+
+- Enable validation of user data
+- Enable serialization and deserialization of metadata files
+- Support versioning of the metadata format
+- Enforce consistency across multiple tools
+
+## Release
+
+This packaged is built and released using the Maven Release Plugin and Github Actions.
+
+To release a new version simply create a branch prefixed with `release-java` and everything else is taken care of, including version increment, tagging, building, pushing artifacts and a GitHub release.

generated/python/datadoc_model/README.md

@@ -11,12 +11,6 @@ This package contains pydantic models defining the fields and data types used in
 - Support versioning of the metadata format
 - Enforce consistency across multiple tools
 
-## Single Source of Truth
+## Release
 
-Fields and data types defined in models in this package are specified on internal Statistics Norway wiki pages:
-
-- <https://statistics-norway.atlassian.net/l/cp/kQ9rpshS>
-
-## Code generation
-
-The models are defined as [JSON Schema](https://json-schema.org/) documents. These reside within the `src/` directory in this repo. Code for a range of languages is generated from the JSON Schema and will live inside the `generated/` directory, with a subdirectory for each language.
+To release this package, create a branch and run `poetry version [patch | minor | major]` depending on your change. Once the branch is merged, a GitHub Actions workflow handles the rest.