started on versioning (#31)

* started on versioning

* first version of versioning ready

source/content/index.md

@@ -9,5 +9,6 @@ commands/index
 update_cycle/index
 principles/index
 feature_branch/index
+versioning/index
 exercise/index
 ```

source/content/versioning/benefits.md

@@ -0,0 +1,12 @@
+{% if slide %}### Benefits{% endif %}
+
+:::{card}{% if page %} Benefits{% endif %}
+
+- Integrates perfectly with `git tag`:
+  ```bash
+  git tag -a X.Y.Z -m 'short description of state'
+  ```
+- Easy to understand and communicate changes to your software.
+- Helps users and developers understand the impact of updates.
+- Simplifies dependency management and versioning.
+:::

source/content/versioning/index.md

@@ -0,0 +1,34 @@
+# Versioning
+
+{% if page %}
+Documenting the state of a repository can be approached in various ways.
+However, to enhance both readability and functionality, we strongly recommend following a consistent structure when describing its state.
+One key element of this structure could be a version identifier.
+{% endif %}
+
+[Versioning](https://en.wikipedia.org/wiki/Software_versioning) provides a logical framework for creating labels that represent specific states of a repository.
+{% if page %}By doing so, it establishes a structured way to describe those states.
+The exact logic followed can vary depending on the chosen versioning approach, and there are many to choose from.
+
+Determining the best versioning approach can be somewhat subjective.
+However, certain methods are more widely adopted than others.
+{% endif %}Here, we present one of the most common approaches:
+{% if page %}[SemVer](https://wwww.semver.org).{% endif %}
+
+
+{% if build == "slides" %}
+<!-- BUILDING THE SLIDES -->
+```{toctree}
+:maxdepth: 1
+:caption: SemVer
+
+./semver
+./benefits
+```
+{% else %}
+<!-- BUILDING THE PAGES -->
+```{include} ./semver.md
+```
+```{include} ./benefits.md
+```
+{% endif %}

source/content/versioning/semver.md

@@ -0,0 +1,21 @@
+## Semantic Versioning
+
+In short SemVer is versioning system that uses a three-part number ({math}`X.Y.Z`) to track changes to your software.
+
+```{math}
+:label: SemVer
+
+\underset{\overbrace{\text{Major}}}{\bf{X}}.\overset{\underbrace{\text{Minor}}}{\bf{Y}}.\underset{\overbrace{\text{Patch}}}{\bf{Z}}
+```
+
+::::{grid}
+:::{grid-item-card} Major
+Increment when you make breaking changes or significant updates.
+:::
+:::{grid-item-card} Minor
+Increment when you add new features or functionality.
+:::
+:::{grid-item-card} Patch
+Increment when you make bug fixes or minor updates.
+:::
+::::

source/index.md

@@ -13,5 +13,6 @@ content/commands/index
 content/update_cycle/index
 content/principles/index
 content/feature_branch/index
+content/versioning/index
 content/exercise/index
 ```