added a utility library for version and updated docs

Author: frogrammer9

docs/doxygen/groups.dox

@@ -12,5 +12,6 @@
 	@defgroup types
 	@defgroup string
 	@defgroup bitutils
+	@defgroup stdversion
 @defgroup trap Interrupt and exception handling
 */

docs/source/pages/api/libs/stdbigos/version.rst

@@ -0,0 +1,5 @@
+=======
+Version
+=======
+
+.. doxygengroup:: stdversion

docs/source/pages/bigos/general/versioning.rst

@@ -2,13 +2,66 @@ Versioning
 ==========
 
 :Author: Oskar Meler
-:Date: 24-02-2026
-:Revision: 1
+:Date: 19-05-2026
+:Revision: 2
 
-All version numbers in BigOS follow the `Major.Minor.Patch` format.
 
-* **Major** – Increment this when changes are made to existing interfaces that break backward compatibility.
+Versioning Scheme
+-----------------
 
-* **Minor** – Increment this when additions or backward-compatible changes are made to the interface.
+All BigOS version numbers follow the ``generation.feature.patch`` format.
 
-* **Patch** – Increment this for bug fixes or other non-breaking corrections.
+Generation
+^^^^^^^^^^
+Incremented when breaking changes are made to existing interfaces or formats.
+A change in Generation indicates **backward-incompatible modifications**.
+
+Feature
+^^^^^^^
+Incremented when new functionality is added in a backward-compatible manner.
+Feature updates do not break compatibility with older versions within the same Generation.
+
+Patch
+^^^^^
+Incremented for bug fixes, internal improvements, and other non-breaking changes that do not affect interface behavior or compatibility.
+
+
+Data Format vs Software Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+BigOS distinguishes between:
+
+Software version (S)
+    The version of the running BigOS implementation (the reader/consumer).
+
+Data format version (F)
+    The version of the serialized or on-disk data being interpreted.
+
+The compatibility rules define whether a given software version can correctly read a given data format version.
+
+
+Compatibility Rule
+~~~~~~~~~~~~~~~~~~
+
+A software version ``S`` is compatible with a data format version ``F`` if and only if the following conditions are met:
+
+- S.generation == F.generation
+- S.feature ≥ F.feature
+
+Patch versions do not affect compatibility.
+
+
+Version Limits
+~~~~~~~~~~~~~~
+
+Version components are constrained as follows:
+
+- Generation ≤ 1024
+- Feature ≤ 1024
+- Patch ≤ 4096
+
+
+Implementation Notes
+~~~~~~~~~~~~~~~~~~~~
+
+stdbigos provides a :doc:`utility library </pages/api/libs/stdbigos/version>` for working with version values.

include/stdbigos/version.h

@@ -0,0 +1,30 @@
+#ifndef STDBIGOS_VERSION
+#define STDBIGOS_VERSION
+
+/// @addtogroup stdbigos
+/// @{
+/// @addtogroup stdversion
+/// @{
+
+#include "stdbigos/types.h"
+
+typedef struct {
+	u16 generation;
+	u16 feature;
+	u16 patch;
+} version_t;
+
+typedef u32 version_packed_t;
+
+version_t version_make(u16 generation, u16 feature, u16 patch);
+
+version_packed_t version_pack(version_t v);
+version_t version_unpack(version_packed_t v);
+
+bool version_is_compatible(version_t current, version_t required);
+bool version_packed_is_compatible(version_packed_t current, version_packed_t required);
+
+/// @}
+/// @}
+
+#endif // !STDBIGOS_VERSION

src/lib/stdbigos/version.c

@@ -0,0 +1,29 @@
+#include "stdbigos/version.h"
+
+version_t version_make(u16 generation, u16 feature, u16 patch) {
+	return (version_t){.generation = generation, .feature = feature, .patch = patch};
+}
+
+version_packed_t version_pack(version_t v) {
+	version_packed_t generation_packed = ((version_packed_t)v.generation & 0x3ffull) << 22;
+	version_packed_t feature_packed = ((version_packed_t)v.feature & 0x3ffull) << 12;
+	version_packed_t patch_packed = ((version_packed_t)v.patch & 0xfffull);
+	return generation_packed | feature_packed | patch_packed;
+}
+
+version_t version_unpack(version_packed_t v) {
+	version_packed_t generation = v >> 22;
+	version_packed_t feature = (v >> 12) & 0x3ffull;
+	version_packed_t patch = v & 0xfffull;
+	return (version_t){.generation = generation, .feature = feature, .patch = patch};
+}
+
+bool version_is_compatible(version_t current, version_t required) {
+	return current.generation == required.generation && current.feature >= required.feature;
+}
+
+bool version_packed_is_compatible(version_packed_t current, version_packed_t required) {
+	version_t currentu = version_unpack(current);
+	version_t requiredu = version_unpack(required);
+	return currentu.generation == requiredu.generation && currentu.feature >= requiredu.feature;
+}