From 2ace752ba446e1177fb32443bc6632f6fa04d598 Mon Sep 17 00:00:00 2001
From: kevin <68426071+hf-krechan@users.noreply.github.com>
Date: Wed, 27 Dec 2023 13:40:43 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Fix=20Documentation=20Build=20on?=
 =?UTF-8?q?=20ReadTheDocs=20And=20Add=20Documentation=20About=20Versioning?=
 =?UTF-8?q?=20(#673)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/conf.py        |  3 +++
 docs/index.rst      |  6 ++++--
 docs/versioning.rst | 30 ++++++++++++++++++++++++++++++
 src/bo4e/version.py |  7 +++++--
 4 files changed, 42 insertions(+), 4 deletions(-)
 create mode 100644 docs/versioning.rst

diff --git a/docs/conf.py b/docs/conf.py
index a2a362704..23b8f3e3f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -24,6 +24,9 @@
 sys.path.insert(0, os.path.join(__location__, "../docs"))
 from uml import PlantUMLNetwork, build_network, compile_files_kroki, write_class_umls
 
+# import package bo4e to clarify namespaces and prevent circular import errors
+from bo4e import *
+
 # -- Run sphinx-apidoc ------------------------------------------------------
 # This hack is necessary since RTD does not issue `sphinx-apidoc` before running
 # `sphinx-build -b html . _build/html`. See Issue:
diff --git a/docs/index.rst b/docs/index.rst
index e38ebf77c..06bcf77ed 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,9 @@
 =============
-bo4e
+BO4E
 =============
 
-This is the documentation of **bo4e** python package.
+This is the official documentation of **BO4E** datamodel.
+Cause of the fact that the datamodel is written in Python, it is also the Python documentation.
 
 
 Contents
@@ -13,6 +14,7 @@ Contents
 
    License <license>
    Authors <authors>
+   Versioning <versioning>
    Changelog <changelog>
    Module Reference <api/modules>
 
diff --git a/docs/versioning.rst b/docs/versioning.rst
new file mode 100644
index 000000000..66602b820
--- /dev/null
+++ b/docs/versioning.rst
@@ -0,0 +1,30 @@
+===============
+BO4E Versioning
+===============
+
+The BO4E data model uses a unique versioning system to track changes and updates.
+This system is easy to understand once you're familiar with its format and rationale.
+
+Let's break it down:
+
+Version Format: `YYYYMM.functional.technical`
+
+- YYYYMM: Represents the year (YYYY) and month (MM) when the version was released. For example, 202312 would mean December 2023.
+- functional: A number that changes when there are significant updates or new features.
+- technical: This number changes for minor updates, like bug fixes or spelling corrections.
+
+How Does it Work?
+=================
+
+1. **Base Structure**: Think of the version number as a date followed by two additional numbers, like 202312.1.2. Here, 202312 tells you the release date, 1 is the functional number, and 2 is the technical number.
+2. **Technical Changes**: If we fix a typo or a small bug, we only change the technical number. So, after a minor fix, the version might change from 202312.1.2 to 202312.1.3.
+3. **Functional Changes**: For bigger changes, like adding a new business object, we update the functional number and reset the technical number to zero. For instance, if we add a significant feature to the 202312.1.2 version, it becomes 202312.2.0.
+
+Yearly Reset: With the start of a new year, we reset both the functional and technical numbers.
+So, if we're moving from December 2023 (202312.2.0) to January 2024, the new version would be 202401.0.0.
+
+Why This System?
+================
+
+This versioning system, inspired by semantic versioning, offers a clear and systematic way to track changes.
+It ensures that users can easily identify when a significant update has occurred and when minor tweaks have been made.
diff --git a/src/bo4e/version.py b/src/bo4e/version.py
index 7394e6ceb..57d21464d 100644
--- a/src/bo4e/version.py
+++ b/src/bo4e/version.py
@@ -2,9 +2,12 @@
 Version information for the bo4e package.
 """
 import re
-from importlib.metadata import version
+from importlib.metadata import PackageNotFoundError, version
 
-__version__ = version("bo4e")
+try:
+    __version__ = version("bo4e")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
 # Please keep this name in sync with the name of the project in pyproject.toml
 # This name is the name of the package on pypi.org
 if re.match(r"^(\d+\.\d+\.\d+)(rc\d+)?$", __version__):