Add support to create pre-releases with a generated changelog

.github/actions/features_parse/action.yml

@@ -11,7 +11,7 @@ outputs:
 runs:
   using: composite
   steps:
-    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/setup@0.10.8
+    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/setup@0.10.9
     - id: result
       shell: bash
       run: |

.github/actions/flavors_parse/action.yml

@@ -13,7 +13,7 @@ outputs:
 runs:
   using: composite
   steps:
-    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/setup@0.10.8
+    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/setup@0.10.9
     - id: matrix
       shell: bash
       run: |

.github/actions/setup/action.yml

@@ -4,7 +4,7 @@ description: Installs the given GardenLinux Python library
 inputs:
   version:
     description: GardenLinux Python library version
-    default: "0.10.8"
+    default: "0.10.9"
   python_version:
     description: Python version to setup
     default: "3.13"

.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: pre-release
+
+on:
+  push:
+    tags: [ "[0-9]+.[0-9]+.[0-9]+*" ]
+
+jobs:
+  create-pre-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout commit
+      uses: actions/checkout@v6
+      with:
+        sparse-checkout: |
+          cliff.toml
+        sparse-checkout-cone-mode: false
+    - uses: gardenlinux/python-gardenlinux-lib/.github/actions/setup@main
+    - name: Use cargo cache
+      id: cache-cargo
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo
+        key: gh-release-${{ runner.os }}-cargo-${{ hashFiles('~/.cargo/.crates.toml') }}
+        restore-keys: gh-release-${{ runner.os }}-cargo-
+    - name: Install git-cliff
+      if: steps.cache-cargo.outputs.cache-hit != 'true'
+      run: |
+        cargo install git-cliff
+    - name: Get the Git tag name
+      id: get-tag-name
+      run: echo "tag-name=${GITHUB_REF/refs\/tags\//}" | tee -a "$GITHUB_OUTPUT"
+    - id: release
+      name: Create changelog and release
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        gl-gh-release create \
+         --repo "python-gardenlinux-lib" \
+         --tag "${{ steps.get-tag-name.outputs.tag-name }}" \
+         --commit "${{ github.sha }}" \
+         --name 'python-gardenlinux-lib v${{ steps.get-tag-name.outputs.tag-name }}' \
+         --latest \
+         --body "
+         $(git-cliff -o - --current)
+         "

cliff.toml

@@ -0,0 +1,84 @@
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# A Tera template to be rendered as the changelog's header.
+# See https://keats.github.io/tera/docs/#introduction
+header = """
+{% if version -%}
+    # Changelog for {{ version }} }}
+{% else -%}
+    # Changelog
+{% endif -%}
+
+All notable changes since last release will be documented below.
+"""
+# A Tera template to be rendered for each release in the changelog.
+# See https://keats.github.io/tera/docs/#introduction
+body = """
+{%- macro remote_url() -%}
+  https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {%- for commit in commits %}
+        - {{ commit.message | split(pat="\n") | first | upper_first | trim }}\
+            {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}
+            {% if commit.remote.pr_number %} in \
+            [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}) \
+            {%- endif -%}
+    {% endfor %}
+{% endfor %}
+"""
+# A Tera template to be rendered as the changelog's footer.
+# See https://keats.github.io/tera/docs/#introduction
+footer = """
+{%- macro remote_url() -%}
+  https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
+
+{% for release in releases -%}
+    {% if release.version -%}
+        {% if release.previous.version -%}
+            [{{ release.version | trim_start_matches(pat="v") }}]: \
+                {{ self::remote_url() }}/compare/{{ release.previous.version }}...{{ release.version }}
+        {% endif -%}
+    {% else -%}
+        [unreleased]: {{ self::remote_url() }}/compare/{{ release.previous.version }}...HEAD
+    {% endif -%}
+{% endfor %}
+<!-- generated by git-cliff -->
+"""
+# Remove leading and trailing whitespaces from the changelog's body.
+trim = true
+
+[git]
+# Parse commits according to the conventional commits specification.
+# See https://www.conventionalcommits.org
+conventional_commits = true
+# Exclude commits that do not match the conventional commits specification.
+filter_unconventional = false
+# An array of regex based parsers for extracting data from the commit message.
+# Assigns commits to groups.
+# Optionally sets the commit's scope and can decide to exclude commits from further processing.
+commit_parsers = [
+    { message = "^[a|A]dd", group = "Added" },
+    { message = "^[s|S]upport", group = "Added" },
+    { message = "^[r|R]emove", group = "Removed" },
+    { message = "^.*: add", group = "Added" },
+    { message = "^.*: support", group = "Added" },
+    { message = "^.*: remove", group = "Removed" },
+    { message = "^.*: delete", group = "Removed" },
+    { message = "^test", group = "Fixed" },
+    { message = "^fix", group = "Fixed" },
+    { message = "^.*: fix", group = "Fixed" },
+    { message = "^.*", group = "Changed" },
+]
+# Prevent commits that are breaking from being excluded by commit parsers.
+filter_commits = false
+# Order releases topologically instead of chronologically.
+topo_order = true
+# Order of commits in each group/release within the changelog.
+# Allowed values: newest, oldest
+sort_commits = "oldest"

docs/release.rst

@@ -0,0 +1,28 @@
+python-gardenlinux-lib release documentation
+============================================
+
+*python-gardenlinux-lib* strictly follow syntax and intention of `Semantic Versioning <https://www.semver.org>`. Each release reflects the intention and expected impact therefore.
+
+A new release is done by tagging a commit with a valid version. This will create a GitHub pre-release for proof-reading. Once done a new release can be published using GitHub CLI or UI.
+
+Newly added docstrings should contain the first version supporting the new API / command line.
+
+Step by step guide
+------------------
+
+#. *python-gardenlinux-lib* version files:
+
+   *python-gardenlinux-lib* versioning needs to be set in:
+
+   - ``pyproject.toml``
+   - ``.github/actions/setup/action.yml``
+
+   Additionally at the moment (removal pending):
+
+   - ``.github/actions/features_parse/action.yml``
+   - ``.github/actions/flavors_parse/action.yml``
+
+#. ``git tag <tag>``
+#. Review the generated changelog and publish it if applicable.
+#. Projects consuming the *python-gardenlinux-lib* may use the following git URL for dependency definition:
+   ``gardenlinux @ git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0``