[#189] ci: automate release versioning and dry-run support in publish workflow

.github/workflows/release-to-central.yml

@@ -1,6 +1,16 @@
 name: Publish artifact
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version (e.g. 1.5.0). Must be greater than or equal to the current version in the pom.xml.'
+        required: true
+      dry_run:
+        description: 'Dry run: validate, build and sign without publishing to Maven Central or pushing any commits/tags.'
+        required: true
+        default: false
+        type: boolean
 
 jobs:
   build:
@@ -25,6 +35,27 @@ jobs:
           server-id: central
           server-username: MAVEN_USERNAME
           server-password: MAVEN_CENTRAL_TOKEN
+      - name: Validate release version
+        run: |
+          CURRENT_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout | sed 's/-SNAPSHOT//')
+          INPUT_VERSION="${{ inputs.version }}"
+          LOWER=$(printf '%s\n%s\n' "$INPUT_VERSION" "$CURRENT_VERSION" | sort -V | head -1)
+          if [ "$LOWER" = "$INPUT_VERSION" ] && [ "$INPUT_VERSION" != "$CURRENT_VERSION" ]; then
+            echo "::error::Release version $INPUT_VERSION is lower than the current pom version $CURRENT_VERSION. Refusing to release."
+            exit 1
+          fi
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Set release version
+        run: mvn -B versions:set -DnewVersion=${{ inputs.version }} -DgenerateBackupPoms=false
+      - name: Commit and tag release version
+        if: ${{ inputs.dry_run == false }}
+        run: |
+          git add pom.xml
+          git commit -m "Release version ${{ inputs.version }}"
+          git tag -a "v${{ inputs.version }}" -m "Release v${{ inputs.version }}"
       - name: Package and verify
         env:
           MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
@@ -43,5 +74,17 @@ jobs:
           JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           JRELEASER_MAVENCENTRAL_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
           JRELEASER_MAVENCENTRAL_TOKEN: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+        run: mvn -Prelease jreleaser:full-release ${{ inputs.dry_run == true && '--dry-run' || '' }}
+      - name: Set next SNAPSHOT version
+        if: ${{ inputs.dry_run == false }}
         run: |
-          mvn -Prelease jreleaser:full-release
+          MAJOR=$(echo "${{ inputs.version }}" | cut -d. -f1)
+          MINOR=$(echo "${{ inputs.version }}" | cut -d. -f2)
+          PATCH=$(echo "${{ inputs.version }}" | cut -d. -f3)
+          NEXT_VERSION="${MAJOR}.${MINOR}.$((PATCH+1))-SNAPSHOT"
+          mvn -B versions:set -DnewVersion=${NEXT_VERSION} -DgenerateBackupPoms=false
+          git add pom.xml
+          git commit -m "Prepare next development iteration ${NEXT_VERSION}"
+      - name: Push release commit, tag, and next SNAPSHOT commit
+        if: ${{ inputs.dry_run == false }}
+        run: git push origin main --follow-tags

CONTRIBUTING.md

@@ -4,23 +4,55 @@ Thank you for considering contributing to this project! Here are some guidelines
 
 ## Reporting Issues
 
-If you find a bug, have an idea for an enhancement, or want to start a discussion, please file an issue in the repository. Make sure to provide as much detail as possible to help us understand and address the issue. A reproduction of the issue, including steps to reproduce, is always helpful.
+If you find a bug, have an idea for an enhancement, or want to start a discussion, please file an issue in the
+repository. Make sure to provide as much detail as possible to help us understand and address the issue. A reproduction
+of the issue, including steps to reproduce, is always helpful.
 
 ## Branch Naming
 
-When working on an issue, create a new branch starting with `issue-xx` where `xx` is the number of the issue. For example, if you are working on issue #42, your branch should be named `issue-42-the-issue-to-be-fixed`.
+When working on an issue, create a new branch starting with `issue-xx` where `xx` is the number of the issue. For
+example, if you are working on issue #42, your branch should be named `issue-42-the-issue-to-be-fixed`.
 
 ## Submitting a Pull Request
 
 1. Run `mvn verify` to ensure your changes pass all tests and styling.
-2. Commit your changes to your branch on your fork. [How to create a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+2. Commit your changes to your branch on your
+   fork. [How to create a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
 3. Push your branch to your forked repository.
 4. Submit a pull request (PR) from your forked repository to the main repository.
 5. Reference the issue number in your PR description.
 
 ## Code Style
 
-Please ensure your code adheres to the project's coding standards and passes all tests. This helps maintain code quality and consistency.
+Please ensure your code adheres to the project's coding standards and passes all tests. This helps maintain code quality
+and consistency.
+
+## Releasing
+
+### Required GitHub secrets
+
+The following secrets must be configured once under **Settings → Secrets and variables → Actions**:
+
+| Secret                       | Description                                          |
+|------------------------------|------------------------------------------------------|
+| `GPG_PRIVATE_KEY`            | ASCII-armored GPG private key used to sign artifacts |
+| `GPG_PUBLIC_KEY`             | ASCII-armored GPG public key                         |
+| `GPG_PRIVATE_KEY_PASSPHRASE` | Passphrase for the GPG key                           |
+| `MAVEN_CENTRAL_USERNAME`     | Maven Central (Sonatype) username                    |
+| `MAVEN_CENTRAL_PASSWORD`     | Maven Central (Sonatype) token                       |
+
+### How to release
+
+1. Go to **Actions → Publish artifact → Run workflow**.
+2. Enter the release version (e.g. `1.5.0`). It must be ≥ the version currently in `pom.xml` (minus `-SNAPSHOT`).
+3. Click **Run workflow**.
+
+The workflow will:
+
+- Set the `pom.xml` version to the release version, commit, and tag it.
+- Sign, build, and publish the artifacts to Maven Central.
+- Bump the `pom.xml` to the next patch SNAPSHOT (e.g. `1.5.1-SNAPSHOT`) and commit.
+- Push all commits and the tag to `main`.
 
 ## Thank You