From 98fc2ad9e2897ad425f750c1015f5e30c8941dd1 Mon Sep 17 00:00:00 2001
From: Noel Gomez <noel_gomez@yahoo.com>
Date: Mon, 16 Sep 2024 09:31:42 -0700
Subject: [PATCH] add versioning page (#42)

---
 docs/_sidebar.md                       |  3 +-
 docs/reference/datacoves/versioning.md | 40 ++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/datacoves/versioning.md

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 8361a9a..01ca9c1 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -89,7 +89,8 @@
     - [DAG Generators](/reference/airflow/dag-generators.md)
     - [Datacoves Operators](/reference/airflow/datacoves-operator.md)
   - [Datacoves](/reference/datacoves/)
-    - [VPC Deployment](/reference/datacoves/vpc-deployment.md)  
+    - [Versioning](/reference/datacoves/versioning.md)
+    - [VPC Deployment](/reference/datacoves/vpc-deployment.md) 
   - [Metrics & Logs](/reference/metrics-and-logs/)
     - [Grafana](/reference/metrics-and-logs/grafana.md)
   - [Security](/reference/security/)
diff --git a/docs/reference/datacoves/versioning.md b/docs/reference/datacoves/versioning.md
new file mode 100644
index 0000000..fb0b825
--- /dev/null
+++ b/docs/reference/datacoves/versioning.md
@@ -0,0 +1,40 @@
+# Datacoves versioning
+
+Datacoves uses [semantic versioning](https://semver.org/) in all our docker images, and Datacoves releases.
+
+`MAJOR.MINOR.PATCH`
+
+The `MAJOR.MINOR` versions are defined as below and `PATCH` is an autogenerated (timestamp) generated when the release is built.
+
+## Our criteria
+
+### When do we bump the `MAJOR` version?
+
+When we make incompatible changes or we introduce compatible changes but deprecate features:
+
+- Any python library upgrade (including dbt) that requires changes in the customer's analytics(dbt) git repo
+- Airbyte, Airflow, DataHub, Superset upgrades that require reconfiguration
+- Datacoves core changes that require human intervention
+- Airbyte, Airflow, DataHub, Superset that do not require reconfiguration, but several features are being deprecated
+
+### When should we bump the `MINOR` version?
+
+- When we make compatible changes, such as new features or upgrade dependencies
+- Patch version changes to dbt e.g. 1.8.3 to 1.8.5
+- Compatible updates to dbt e.g. 1.7.x to 1.8.x
+- Compatible update to Airbyte, Airflow, DataHub, Superset that do not require reconfiguration
+
+### Everything else is a `PATCH`
+
+- Bug fixes, performance enhancements
+
+## Images tags
+
+Images are pushed with the folling tags:
+
+- MAJOR
+- MAJOR.MINOR
+- MAJOR.MINOR.PATCH
+- MAJOR.MINOR.PATCH-\<commit sha\>
+
+CI jobs that use Datacoves images could reference any of the above, depending on how specific the customer needs to be.