TENT-5945 feat: Switch from semver to Cadenza version based versioning

.github/workflows/release-legacy.yml

@@ -0,0 +1,97 @@
+# This workflow should only be used for Semantic versioning based releases of cadenza.js versions used in Cadenza 10.1
+# and earlier. Starting with 10.2 we do not use Semantic versioning in the classic way.
+
+name: Legacy Release (Cadenza 10.1 and earlier)
+
+on:
+  workflow_dispatch:
+    inputs:
+      release-type:
+        type: choice
+        description: 'Release type'
+        required: true
+        options:
+          - patch
+          - minor
+          - major
+        default: 'patch'
+
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/create-github-app-token@v1
+      id: app-token
+      with:
+        app-id: ${{ vars.DISY_RELEASE_APP_ID }}
+        private-key: ${{ secrets.DISY_RELEASE_APP_SECRET }}
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        token: ${{ steps.app-token.outputs.token }}
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version-file: package.json
+        cache: 'npm'
+
+    - run: npm ci
+    - run: npm test
+    - run: npm run build
+
+    # Needed for creating the tag
+    - name: Configure Git
+      run: |
+        git config --global user.email "github-actions[bot]@users.noreply.github.com"
+        git config --global user.name "github-actions[bot]"
+
+    - name: Bump package version
+      run: |
+        echo "NEW_VERSION=$(npm --no-git-tag-version version ${{ github.event.inputs.release-type }})" >> $GITHUB_ENV
+        echo "RELEASE_TAG=latest" >> $GITHUB_ENV
+
+    # Update changelog unreleased section with new version
+    - name: Update changelog
+      uses: superfaceai/release-changelog-action@v2
+      with:
+        path-to-changelog: CHANGELOG.md
+        version: ${{ env.NEW_VERSION }}
+        operation: release
+
+    - name: Commit and tag changes
+      run: |
+        git add "package.json"
+        git add "CHANGELOG.md"
+        git commit -m "chore: release ${{ env.NEW_VERSION }}"
+        git tag ${{ env.NEW_VERSION }}
+
+    - name: Push changes
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: git push origin && git push --tags
+
+    - id: get-changelog
+      name: Get version changelog
+      uses: superfaceai/release-changelog-action@v2
+      with:
+        path-to-changelog: CHANGELOG.md
+        version: ${{ env.NEW_VERSION }}
+        operation: read
+
+    - name: Update GitHub release documentation
+      uses: softprops/action-gh-release@v1
+      with:
+        tag_name: ${{ env.NEW_VERSION }}
+        body: ${{ steps.get-changelog.outputs.changelog }}
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Publish npm package
+      run: |
+        npm config set '//registry.npmjs.org/:_authToken' "${NPM_TOKEN}"
+        npm publish --verbose --access=public --tag=${{ env.RELEASE_TAG }}
+      env:
+        NPM_TOKEN: ${{ secrets.NPMJS_ACCESS_TOKEN }}

.github/workflows/release.yml

@@ -1,24 +1,34 @@
+# This workflow should only be used for version releases for cadenza.js versions bundled with
+# Cadenza 10.2 and later. Starting with 10.2 we do not use Semantic versioning in the classic way any longer.
+# For earlier versions use the "Legacy Release" workflow.
+
 name: Release
 
 on:
   workflow_dispatch:
     inputs:
-      release-type:
-        type: choice
-        description: 'Release type'
-        required: true
-        options:
-          - patch
-          - minor
-          - major
-        default: 'patch'
+      cadenza-version:
+        type: string
+        description: |
+          Cadenza Version
+          (When given in format x.x, a major x.x.0 version is released. Otherwise, the patch version number of the
+          current version is increased)'
+        required: false
 
 
 jobs:
   release:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Validate version input
+      if: "${{ github.event.inputs.cadenza-version != '' }}"
+      run: |
+        if ! [[ '${{ github.event.inputs.cadenza-version }}' =~ ^[0-9]+\.[0-9]+$ ]]; then
+          echo "Cadenza Version must be specified in the format x.x (e.g. 10.2). Was '${{ github.event.inputs.cadenza-version }}'." >&2
+          exit 1
+        fi
+
     - uses: actions/create-github-app-token@v1
       id: app-token
       with:
@@ -45,10 +55,16 @@ jobs:
         git config --global user.email "github-actions[bot]@users.noreply.github.com"
         git config --global user.name "github-actions[bot]"
 
-    - name: Bump package version
-      run: |
-        echo "NEW_VERSION=$(npm --no-git-tag-version version ${{ github.event.inputs.release-type }})" >> $GITHUB_ENV
-        echo "RELEASE_TAG=latest" >> $GITHUB_ENV
+    - name: Bump package version (patch)
+      if: "${{ github.event.inputs.cadenza-version == '' }}"
+      run: echo "NEW_VERSION=$(npm --no-git-tag-version version patch)" >> $GITHUB_ENV
+
+    - name: Bump package version (Cadenza major release)
+      if: "${{ github.event.inputs.cadenza-version != '' }}"
+      run: echo "NEW_VERSION=${{ github.event.inputs.cadenza-version }}.0" >> $GITHUB_ENV
+
+    - name: Set release tag to 'latest'
+      run: echo "RELEASE_TAG=latest" >> $GITHUB_ENV
 
     # Update changelog unreleased section with new version
     - name: Update changelog

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Changed
+- Switch from Semantic versioning to Cadenza Version based versioning (Starting with Cadenza 10.2)
 
 ## 2.13.1 - 2024-09-24
 ### Fixed

src/docs.md

@@ -10,12 +10,17 @@ Cadenza JS is a JavaScript library to use the [disy Cadenza](https://www.disy.ne
 
 Cadenza JS is included in the Cadenza distribution in the corresponding version.
 
-Alternatively you can install the most recent version using npm:
+Alternatively you can install the most recent version for a particular Cadenza Release using npm:
 
 ```bash
-npm install @disy/cadenza.js
+npm install @disy/cadenza.js@~10.2.0 # For latest version for Cadenza 10.2 
 ```
 
+The Cadenza Version is reflected in the cadenza.js version (e.g. 10.2.0 for Cadenza 10.2), while the last version segment is increased for both, bugfixes and functional changes.
+
+### Cadenza 10.1 and earlier
+For Cadenza 10.1 and earlier versions cadenza.js used did use genuine semantic versioning. Please consult the Cadenza Documentation for the corresponding major and minor version of cadenza.js.
+
 ## Usage Examples
 
 This section features usage examples for Cadenza JS. For detailed usage information, see the "API:" links.