From ed64c96ca8dc114f8a9ab97dee4fbb6658a5f07e Mon Sep 17 00:00:00 2001 From: Miles Mason Winther <42948872+mmwinther@users.noreply.github.com> Date: Mon, 4 Dec 2023 15:48:14 +0100 Subject: [PATCH] Update documentation (#24) * Describe versioning in general * Fix up READMEs for the code packages * Specify files for documentation label --- .github/release-drafter-java.yml | 6 ++- .github/release-drafter-python.yml | 6 ++- README.md | 54 +++++++++++++++++++++--- generated/java/datadoc-model/README.md | 18 ++++++++ generated/python/datadoc_model/README.md | 10 +---- 5 files changed, 76 insertions(+), 18 deletions(-) create mode 100644 generated/java/datadoc-model/README.md diff --git a/.github/release-drafter-java.yml b/.github/release-drafter-java.yml index e8dbbb87..33ff60a5 100644 --- a/.github/release-drafter-java.yml +++ b/.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\/.+/' diff --git a/.github/release-drafter-python.yml b/.github/release-drafter-python.yml index 232c914e..9eb32573 100644 --- a/.github/release-drafter-python.yml +++ b/.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\/.+/' diff --git a/README.md b/README.md index 99cadea6..fd7c483b 100644 --- a/README.md +++ b/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: - -- +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. diff --git a/generated/java/datadoc-model/README.md b/generated/java/datadoc-model/README.md new file mode 100644 index 00000000..86ac91b7 --- /dev/null +++ b/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. diff --git a/generated/python/datadoc_model/README.md b/generated/python/datadoc_model/README.md index 99cadea6..c2d82610 100644 --- a/generated/python/datadoc_model/README.md +++ b/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: - -- - -## 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.