Restructuring

Scaseco · Feb 16, 2024 · 57a310c · 57a310c
1 parent 693b511
commit 57a310c
Show file tree

Hide file tree

Showing 5 changed files with 43 additions and 3 deletions.
diff --git a/docs/artifact-naming.md → docs/concepts/artifact-naming.md b/docs/artifact-naming.md → docs/concepts/artifact-naming.md
@@ -1,7 +1,7 @@
 ---
 title: Artifact Naming
 layout: default
-nav_order: 30
+nav_order: 20
 ---
 
 ## Artifact Naming

diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -0,0 +1,9 @@
+---
+title: Concepts
+layout: default
+nav_order: 20
+has_children: true
+---
+
+# Concepts
+
diff --git a/docs/introduction.md → docs/concepts/introduction-to-maven.md b/docs/introduction.md → docs/concepts/introduction-to-maven.md
@@ -1,7 +1,8 @@
 ---
 title: Introduction to Maven
 layout: default
-nav_order: 20
+parent: Concepts
+nav_order: 10
 ---
 
 # An Introduction to Maven

diff --git a/docs/concepts/version-design.md b/docs/concepts/version-design.md
@@ -0,0 +1,29 @@
+---
+title: Version Design
+layout: default
+nav_order: 18
+---
+
+## Version Design Considerations
+
+* Semantic Versioning: A semantic version string is made up from 3 integers in the format `major.minor.incremental`.
+
+An increment in only the ...
+  * ... `incremental` component signifies a non-breaking bug fix.
+  * ... `minor` component signifies a non-breaking feature addition.
+  * ... `major` component signifies a breaking change.
+
+Translating these to datasets would roughly mean:
+
+* An incremental update would be fixing labels
+* A minor update would be the addition of new instances and properties
+* A major update would be schema changes or the removal of instances or properties (as those instances may have been referenced in the downstream process)
+
+* It may be tempting to use the format `yyyy.MM.dd` such as `<version>2024.02.15</version>`, however this may make it difficult to publish updated versions of data at that time later on. For example,
+if it turns out there was a bug in the data generator and several versions are broken.
+
+
+Possible mitigations:
+* Make the data generator revision part of the groupId such as `<groupId>org.myorg.myproject.datagen.v2</groupId>`
+* Reserve the major version field for revisions `<version>1.20240215.0</version>`
+
diff --git a/docs/version-design.md b/docs/version-design.md
@@ -1,7 +1,8 @@
 ---
 title: Version Design
 layout: default
-nav_order: 18
+parent: Concepts
+nav_order: 30
 ---
 
 ## Version Design Considerations