From e95731a7a9adacb9e5474d01f8ad520c1fc872a8 Mon Sep 17 00:00:00 2001
From: Jan Jambor <jan.jambor@xwr.ch>
Date: Wed, 22 May 2024 10:46:53 +0200
Subject: [PATCH] =?UTF-8?q?update:=20Verbesserung=20der=20Dokumentation=20?=
 =?UTF-8?q?und=20des=20Skripts=20f=C3=BCr=20die=20Erstellungb=20eines=20Ch?=
 =?UTF-8?q?ange=20Logs.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .order                               |  2 ++
 CHANGELOG.md                         | 26 ++++++++++++++
 resources/scripts/release-notes.bash | 24 +++++++------
 versioning.md                        | 52 +++++++++++++++++++++++++---
 4 files changed, 88 insertions(+), 16 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/.order b/.order
index a2f88ee..f724cc2 100644
--- a/.order
+++ b/.order
@@ -6,4 +6,6 @@ documentation-guidelines
 versioning
 code-review-process
 network
+service-catalogue
 faq
+CHANGELOG
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..83981a8
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,26 @@
+## Release Notes from 2024-04-18-final-1 to this release
+
+New Features:
+
+- Added a repo for Docker-Compose applications.
+
+Updated Features:
+
+- Example script for release notes updated to better output changes for release notes
+- Guidlines and test script for git commit based release notes
+- Improve onboarding documentation and include lessons learned from customer projects.
+- Improved versioning and added examples for commit messages
+- moved content from former seperated "agile working" repo
+
+Fixed Features:
+
+- Korrektur der Aufzählungszeichen in der Dokumentation "Versioning".
+- outgoing url link name
+- outgoing urls
+- release notes script further tested and fixed
+- remove reference to non-existing content
+- update repo overview and diagram
+
+Deleted Features:
+
+- removed reference to former seperated agile working repo
diff --git a/resources/scripts/release-notes.bash b/resources/scripts/release-notes.bash
index 6337687..7dc8d62 100644
--- a/resources/scripts/release-notes.bash
+++ b/resources/scripts/release-notes.bash
@@ -44,45 +44,47 @@ else
 fi
 
 # Print release notes
-echo ""
-echo "Release Notes from $latestTag to HEAD:"
+echo "## Release Notes from $latestTag to this release"
 echo ""
 
 # Fetch commit logs from the latest tag to HEAD and categorize them
-newfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'new:' | sed 's/new:/* /g' | sort | uniq)
-updatedfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'update:' | sed 's/update:/* /g' | sort | uniq)
-fixedfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'fix:' | sed 's/fix:/* /g' | sort | uniq)
-deletedfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'delete:' | sed 's/delete:/* /g' | sort | uniq)
+newfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'new:' | sed 's/new:/-/g' | sort | uniq)
+updatedfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'update:' | sed 's/update:/-/g' | sort | uniq)
+fixedfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'fix:' | sed 's/fix:/-/g' | sort | uniq)
+deletedfeatures=$(git log "$latestTag"..HEAD --pretty=format:"%s" | grep 'delete:' | sed 's/delete:/-/g' | sort | uniq)
 
 # Output formatted commit lists
 echo "New Features:"
+echo ""
 if [ -z "$newfeatures" ]; then
-    echo "* No new features."
+    echo "- No new features."
 else
     echo "$newfeatures"
 fi
 echo ""
 
 echo "Updated Features:"
+echo ""
 if [ -z "$updatedfeatures" ]; then
-    echo "* No updated features."
+    echo "- No updated features."
 else
     echo "$updatedfeatures"
 fi
 echo ""
 
 echo "Fixed Features:"
+echo ""
 if [ -z "$fixedfeatures" ]; then
-    echo "* No fixed features."
+    echo "- No fixed features."
 else
     echo "$fixedfeatures"
 fi
 echo ""
 
 echo "Deleted Features:"
+echo ""
 if [ -z "$deletedfeatures" ]; then
-    echo "* No deleted features."
+    echo "- No deleted features."
 else
     echo "$deletedfeatures"
 fi
-echo ""
diff --git a/versioning.md b/versioning.md
index 6cd1235..3e85efa 100644
--- a/versioning.md
+++ b/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.