update: Verbesserung der Dokumentation und des Skripts für die Erstellungb eines Change Logs.

versioning.md

@@ -1,4 +1,21 @@
-# Versioning
+# Versioning and Change Logs
+
+Tl;dr:
+
+```bash
+# Base line for change log
+git tag -a 2021-09-final-1 -m "Initial release as base line"
+git push origin 2021-09-final-1
+
+# Add your work
+git commit -m "new: New section xyz has been added."
+git commit -m "fix: Section abc has been improved for better readability."
+
+# Add release notes to CHANGELOG.md
+bash resources/scripts/release-notes.bash > CHANGELOG.md
+```
+
+## Versioning with tags
 
 We utilize a hybrid versioning scheme, blending [Semantic Versioning](https://semver.org/) with [CalVer](https://calver.org/):
 
@@ -16,8 +33,33 @@ Components of the version number are as follows:
   - `final`: Production-ready release.
 - `N`: Incremental release number for multiple releases within one month.
 
-Guidelines:
+To add a tag to a commit you can either use the `git tag` command or the Azure DevOps UI. The following command will add a tag to the latest commit:
 
-- Automated scripts should generate version numbers to avoid errors.
-- Ensure tool compatibility with the hybrid version format.
-- Maintain detailed changelogs for transparency on progression from alpha to final.
+```bash
+git tag -a 2021-09-alpha-1 -m "Initial alpha release"
+git push origin 2021-09-alpha-1
+```
+
+Right now we are manually maintaining the `final` version numbers to ensure that the right commits get the right version number. This is a manual process and can be automated in the future.
+
+## Release Notes from Git Commits
+
+The idea is to get rather automated release notes. To have this as easy as possible, we need:
+
+- key words for the kind of change we applied:
+  - `new:` - for newly added functionality
+  - `update:` - for updated functionality
+  - `fix:` - for fixed functionality
+  - `delete:` - for removed functionality
+  - Everything else will be ignored
+
+- A git commit example for a new feature: `git commit -m "new: added new feature"`
+- A git commit example for something you don't want to show in the release notes (omit any of the keywords at the beginning): `git commit -m "updated readme"`
+
+[resources/scripts/release-notes.bash](resources/scripts/release-notes.bash) is an example bash script to generate the release notes. You can run it with the following command:
+
+```bash
+bash resources/scripts/release-notes.bash
+```
+
+As we don't want to rely 100% on the script output and want to have the possibility to add some manual notes, we will add the release notes to the `CHANGELOG.md` file.