Merge remote-tracking branch 'upstream/master' into fix_2039

.editorconfig

@@ -14,3 +14,10 @@ indent_size = 2
 # The file contains important whitespace at the end of the line in a multi-line string.
 # and editorconfig doesn't seem to respect multi-line strings.
 trim_trailing_whitespace = false
+
+[*.{kt,kts}]
+indent_size = 4
+ij_kotlin_allow_trailing_comma = false
+ij_kotlin_allow_trailing_comma_on_call_site = false
+ktlint_code_style = intellij_idea
+ktlint_standard_function-signature = disabled

.github/actions/setup-jdks/action.yml

@@ -21,7 +21,7 @@ runs:
       uses: actions/setup-java@v4
       with:
         # Temurin JDK 8 for macos on ARM is not available: https://github.com/adoptium/adoptium/issues/96
-        distribution: ${{ runner.os == 'macOS' && 'zulu' || 'temurin' }}
+        distribution: ${{ ((runner.os == 'macOS') && (runner.arch == 'ARM64')) && 'zulu' || 'temurin' }}
         java-version: 8
     - name: Prepare JDK8 env var
       shell: bash

.github/workflows/README.adoc

@@ -0,0 +1,98 @@
+== The YAML workflow files vs. the `*.main.kts` files
+
+The YAML workflow files are generated from the `*.main.kts` files.
+
+These use the https://github.com/typesafegithub/github-workflows-kt[github-workflows-kt]
+Kotlin DSL library to conveniently and type-safely write GitHub Action workflow files.
+
+As there is no official built-in support in GitHub Actions yet until
+https://github.com/orgs/community/discussions/15904 is considered, the YAML files
+need to be generated manually.
+
+There is a safeguard check in all the generated files that this is not forgotten.
+Running a workflow where the according `*.main.kts` produces a different output will
+fail the execution. Additionally, the workflow that runs for pull requests checks
+the consistency of all the YAML files as not all are run for pull requests.
+
+
+
+== Ways to generate the YAML workflow files
+
+There are multiple ways to generate the YAML files and all of them are fine,
+but be aware of the last one of the caveats below if you are not using the Gradle method:
+
+* If you are in a `sh` derivate like e.g. `bash` and Kotlin is installed and
+  available in the `PATH`, you can just call the `*.main.kts` script like any
+  other shell script:
++
+[source,bash]
+----
+$ ./release.main.kts
+----
+
+* If Kotlin is installed somewhere you can call it with the `*.main.kts` script
+  as argument:
++
+[source,bash]
+----
+$ path/to/kotlin release.main.kts
+----
+
+* From the IDE you can create a run configuration that executes the `*.main.kts` script.
+
+* There is a Gradle task `preprocessWorkflows` that generates all YAML files from the
+  according `*.main.kts` files. Additionally, there is also one task per workflow to
+  only generate that one:
++
+[source,bash]
+----
+$ ./gradlew preprocessReleaseWorkflow
+$ ./gradlew preprocessWorkflows
+----
+
+
+
+== Caveats
+
+There are currently three known caveats with the approach we follow.
+
+* https://youtrack.jetbrains.com/issue/KTIJ-16532
++
+If you navigate to a file in the dependencies, only a decompiled file is opened,
+even though the source JAR would be available. Also the quick documentation is missing.
++
+This can easily by mitigated by attaching the library to the normal project
+dependencies while having the need to navigate the source files or while editing them,
+which makes them properly viewable and documentation displayable in the editor.
+
+* https://youtrack.jetbrains.com/issue/KTIJ-14580
++
+We use `@file:Import` to reduce code duplication by having common code in a common file.
+Unfortunately, this triggers a Kotlin IntelliJ plugin bug where the imported file cannot
+be loaded properly and so the things supplied by it like dependencies or common functions
+are not available. This makes most of the workflow `*.main.kts` files red as hell in the
+IDE currently.
++
+To reduce risk for eye-cancer while reading the `*.main.kts` scripts or to be able to
+sanely edit them, temporarily add the `@file:DependsOn` from the imported file to the
+importing file and wait a second, then remove the line again once you are done.
+
+* https://youtrack.jetbrains.com/issue/KT-42101
++
+We use `@file:Import` to reduce code duplication by having common code in a common file.
+Unfortunately, this triggers a Kotlin bug where the compilation cache becomes confused
+if the imported file is changed without the importing file being changed too.
++
+If only the imported file is changed, it could happen that an old version is used,
+or it could also happen that classes added by a `@file:DependsOn` in the imported file
+are not available to the importing file. So if there was a change in the imported file,
+you either need to also change the importing file, or to properly execute the script,
+you need to delete the stale entry from the compilation cache which can be found at for example
+`~/.cache/main.kts.compiled.cache/` on Linux and `%LOCALAPPDATA%\main.kts.compiled.cache\`
+on Windows. Alternatively, you can also delete the whole cache directory.
++
+Another option is to disable the compilation cache for the execution by setting the
+environment variable `KOTLIN_MAIN_KTS_COMPILED_SCRIPTS_CACHE_DIR` or the system property
+`kotlin.main.kts.compiled.scripts.cache.dir` to an empty value, depending on the run
+method you chose. The Gradle tasks already do that, so when using the Gradle tasks you
+do not have this problem and it just works.

.github/workflows/branches-and-prs.main.kts

@@ -0,0 +1,124 @@
+#!/usr/bin/env kotlin
+
+/*
+ * Copyright 2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@file:Import("common.main.kts")
+@file:Repository("https://bindings.krzeminski.it/")
+@file:DependsOn("actions:checkout:v4")
+@file:DependsOn("codecov:codecov-action:v5")
+
+import io.github.typesafegithub.workflows.actions.actions.Checkout
+import io.github.typesafegithub.workflows.actions.actions.Checkout.FetchDepth
+import io.github.typesafegithub.workflows.actions.codecov.CodecovAction
+import io.github.typesafegithub.workflows.domain.Concurrency
+import io.github.typesafegithub.workflows.domain.RunnerType
+import io.github.typesafegithub.workflows.domain.RunnerType.UbuntuLatest
+import io.github.typesafegithub.workflows.domain.triggers.MergeGroup
+import io.github.typesafegithub.workflows.domain.triggers.PullRequest
+import io.github.typesafegithub.workflows.domain.triggers.Push
+import io.github.typesafegithub.workflows.dsl.expressions.Contexts.github
+import io.github.typesafegithub.workflows.dsl.expressions.expr
+import io.github.typesafegithub.workflows.dsl.workflow
+
+workflow(
+    name = "Verify Branches and PRs",
+    on = listOf(
+        Push(
+            branchesIgnore = listOf(
+                "master",
+                "gh-pages"
+            )
+        ),
+        PullRequest(),
+        MergeGroup()
+    ),
+    sourceFile = __FILE__,
+    // https://stackoverflow.com/a/72408109/16358266
+    concurrency = Concurrency(
+        group = "${expr { github.workflow }}-${expr("${github.eventPullRequest.pull_request.number} || ${github.ref}")}",
+        cancelInProgress = true
+    )
+) {
+    job(
+        id = "check_all_workflow_yaml_consistency",
+        name = "Check all Workflow YAML Consistency",
+        runsOn = UbuntuLatest
+    ) {
+        uses(
+            name = "Checkout Repository",
+            action = Checkout()
+        )
+        run(
+            name = "Regenerate all Workflow YAMLs",
+            command = """find .github/workflows -mindepth 1 -maxdepth 1 -name '*.main.kts' -exec {} \;"""
+        )
+        run(
+            name = "Check for Modifications",
+            command = """
+                git add --intent-to-add .
+                git diff --exit-code
+            """.trimIndent()
+        )
+    }
+
+    val matrix = Matrix.full
+    with(__FILE__.parentFile.resolve("../../codecov.yml")) {
+        readText()
+            .replace("after_n_builds:.*+$".toRegex(), "after_n_builds: ${matrix.size}")
+            .let(::writeText)
+    }
+    job(
+        id = "build-and-verify",
+        name = "Build and Verify",
+        runsOn = RunnerType.Custom(expr(Matrix.operatingSystem)),
+        strategy = Strategy(
+            matrix = matrix
+        )
+    ) {
+        uses(
+            name = "Checkout Repository",
+            action = Checkout(
+                // Codecov needs fetch-depth > 1
+                fetchDepth = FetchDepth.Value(2)
+            )
+        )
+        uses(
+            name = "Set up JDKs",
+            action = SetupBuildEnv(
+                additionalJavaVersion = expr(Matrix.javaVersion)
+            )
+        )
+        run(
+            name = "Build Spock",
+            command = listOf(
+                "./gradlew",
+                "--stacktrace",
+                "ghActionsBuild",
+                """"-Dvariant=${expr(Matrix.variant)}"""",
+                """"-DjavaVersion=${expr(Matrix.javaVersion)}""""
+            ).joinToString(" "),
+            // secrets are not injected for pull requests
+            env = commonCredentials
+        )
+        uses(
+            name = "Upload to Codecov.io",
+            action = CodecovAction(
+                failCiIfError = true
+            )
+        )
+    }
+}

.github/workflows/branches-and-prs.yaml

@@ -0,0 +1,116 @@
+# This file was generated using Kotlin DSL (.github/workflows/branches-and-prs.main.kts).
+# If you want to modify the workflow, please change the Kotlin file and regenerate this YAML file.
+# Generated with https://github.com/typesafegithub/github-workflows-kt
+
+name: 'Verify Branches and PRs'
+on:
+  push:
+    branches-ignore:
+    - 'master'
+    - 'gh-pages'
+  pull_request: {}
+  merge_group: {}
+concurrency:
+  group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+  cancel-in-progress: true
+jobs:
+  check_yaml_consistency:
+    name: 'Check YAML consistency'
+    runs-on: 'ubuntu-latest'
+    steps:
+    - id: 'step-0'
+      name: 'Check out'
+      uses: 'actions/checkout@v4'
+    - id: 'step-1'
+      name: 'Execute script'
+      run: 'rm ''.github/workflows/branches-and-prs.yaml'' && ''.github/workflows/branches-and-prs.main.kts'''
+    - id: 'step-2'
+      name: 'Consistency check'
+      run: 'git diff --exit-code ''.github/workflows/branches-and-prs.yaml'''
+  check_all_workflow_yaml_consistency:
+    name: 'Check all Workflow YAML Consistency'
+    runs-on: 'ubuntu-latest'
+    needs:
+    - 'check_yaml_consistency'
+    steps:
+    - id: 'step-0'
+      name: 'Checkout Repository'
+      uses: 'actions/checkout@v4'
+    - id: 'step-1'
+      name: 'Regenerate all Workflow YAMLs'
+      run: 'find .github/workflows -mindepth 1 -maxdepth 1 -name ''*.main.kts'' -exec {} \;'
+    - id: 'step-2'
+      name: 'Check for Modifications'
+      run: |-
+        git add --intent-to-add .
+        git diff --exit-code
+  build-and-verify:
+    name: 'Build and Verify'
+    runs-on: '${{ matrix.os }}'
+    needs:
+    - 'check_yaml_consistency'
+    strategy:
+      fail-fast: false
+      matrix:
+        variant:
+        - '2.5'
+        - '3.0'
+        - '4.0'
+        java:
+        - '8'
+        - '11'
+        - '17'
+        - '21'
+        - '23'
+        os:
+        - 'ubuntu-latest'
+        exclude:
+        - variant: '2.5'
+          java: '17'
+          os: 'ubuntu-latest'
+        - variant: '2.5'
+          java: '21'
+          os: 'ubuntu-latest'
+        - variant: '2.5'
+          java: '23'
+          os: 'ubuntu-latest'
+        include:
+        - variant: '2.5'
+          java: '8'
+          os: 'windows-latest'
+        - variant: '3.0'
+          java: '8'
+          os: 'windows-latest'
+        - variant: '4.0'
+          java: '8'
+          os: 'windows-latest'
+        - variant: '2.5'
+          java: '8'
+          os: 'macos-latest'
+        - variant: '3.0'
+          java: '8'
+          os: 'macos-latest'
+        - variant: '4.0'
+          java: '8'
+          os: 'macos-latest'
+    steps:
+    - id: 'step-0'
+      name: 'Checkout Repository'
+      uses: 'actions/checkout@v4'
+      with:
+        fetch-depth: '2'
+    - id: 'step-1'
+      name: 'Set up JDKs'
+      uses: './.github/actions/setup-build-env'
+      with:
+        additional-java-version: '${{ matrix.java }}'
+    - id: 'step-2'
+      name: 'Build Spock'
+      env:
+        DEVELOCITY_ACCESS_KEY: '${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}'
+      run: './gradlew --stacktrace ghActionsBuild "-Dvariant=${{ matrix.variant }}" "-DjavaVersion=${{ matrix.java }}"'
+    - id: 'step-3'
+      name: 'Upload to Codecov.io'
+      uses: 'codecov/codecov-action@v5'
+      with:
+        fail_ci_if_error: 'true'