Review Feedback Vol. 2

Author: Vampire

.github/workflows/test-script-consuming-jit-bindings.main.do-not-compile.kts

@@ -1,6 +1,7 @@
 #!/usr/bin/env kotlin
 @file:Repository("https://repo.maven.apache.org/maven2/")
 @file:DependsOn("io.github.typesafegithub:github-workflows-kt:1.13.0")
+@file:DependsOn("io.kotest:kotest-assertions-core:5.9.1")
 
 @file:Repository("http://localhost:8080")
 
@@ -13,14 +14,21 @@
 // Using specific version.
 @file:DependsOn("actions:cache:v3.3.3")
 
+// Using version ranges.
+@file:DependsOn("gradle:actions__dependency-submission___major:[v3.3.1,v4-alpha)")
+@file:DependsOn("gradle:actions__wrapper-validation___minor:[v4.2.1,v4.3-alpha)")
+
 // Always untyped action.
 @file:DependsOn("typesafegithub:always-untyped-action-for-tests:v1")
 
 import io.github.typesafegithub.workflows.actions.actions.Cache
 import io.github.typesafegithub.workflows.actions.actions.Checkout
 import io.github.typesafegithub.workflows.actions.actions.Checkout_Untyped
 import io.github.typesafegithub.workflows.actions.gradle.ActionsSetupGradle
+import io.github.typesafegithub.workflows.actions.gradle.ActionsDependencySubmission_Untyped
+import io.github.typesafegithub.workflows.actions.gradle.ActionsWrapperValidation
 import io.github.typesafegithub.workflows.actions.typesafegithub.AlwaysUntypedActionForTests_Untyped
+import io.kotest.matchers.shouldBe
 
 println(Checkout_Untyped(fetchTags_Untyped = "false"))
 println(Checkout(fetchTags = false))
@@ -29,5 +37,8 @@ println(AlwaysUntypedActionForTests_Untyped(foobar_Untyped = "baz"))
 println(ActionsSetupGradle())
 println(Cache(path = listOf("some-path"), key = "some-key"))
 
+ActionsDependencySubmission_Untyped().actionVersion shouldBe "v3"
+ActionsWrapperValidation().actionVersion shouldBe "v4.2"
+
 // Ensure that 'copy(...)' method is exposed.
 Checkout(fetchTags = false).copy(fetchTags = true)

action-binding-generator/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords.kt

@@ -6,6 +6,14 @@ public data class ActionCoords(
     val owner: String,
     val name: String,
     val version: String,
+
+    /**
+     * The version part that is significant when generating the YAML output,
+     * i.e. whether to write the full version, only the major version or major and minor version.
+     * This is used to enable usage of Maven ranges without needing to specify a custom version
+     * each time instantiating an action.
+     * The value of this property is part of the Maven coordinates as a suffix for the [name] property.
+     */
     val significantVersion: SignificantVersion = FULL,
     val path: String? = null,
 )

action-binding-generator/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion.kt

@@ -1,8 +1,24 @@
 package io.github.typesafegithub.workflows.actionbindinggenerator.domain
 
+/**
+ * The version part that is significant when generating the YAML output.
+ * This is used to enable usage of Maven ranges without needing to specify a custom version
+ * each time instantiating an action.
+ */
 public enum class SignificantVersion {
+    /**
+     * Only write the major version to the generated YAML.
+     */
     MAJOR,
+
+    /**
+     * Only write the major and minor version to the generated YAML.
+     */
     MINOR,
+
+    /**
+     * Write the full version to the generated YAML.
+     */
     FULL,
     ;
 

docs/user-guide/using-actions.md

@@ -20,23 +20,35 @@ To add a dependency on an action:
    `gradle/actions/setup-gradle@v3`, replace the slashes in the action name with `__`, so in this case it would be
    `@file:DependsOn("gradle:actions__setup-gradle:v3")`.
 
-   Additionally, the name part can have the suffix `___major` or `___minor`. Without these suffixes if you request
-   a version `v1.2.3`, the generated YAML will also use exactly `v1.2.3` unless you use a custom version override.
-   with the `___major` suffix, it would only write `v1` to the generated YAML, with the `___minor` suffix `v1.2`.
-
-   This is especially useful when combined with a version range. The problem with using `v1` or `v1.2` is, that for
-   GitHub actions these are changing tags or changing branches and not static releases. But in the Maven world
-   a version that does not end in `-SNAPSHOT` is considered immutable and is not expected to change. This means that
-   if a new version of the action is released that adds a new input, you cannot use it easily as you still have the old
-   `v1` artifact in your Maven cache and it will not be updated usually, even though the binding server provides a new
-   binding including the added input.
-
-   To mitigate this problem you can for example use a dependency like `gradle/actions/setup-gradle___major@[v3,v4)`.
-   This will resolve to the latest `v3.x.y` version and thus include any newly added inputs, but still only write `v3`
-   to the YAML. Without the `___major` suffix or a not semantically matching range like `[v3,v5)` or even `[v3,v4]` you
-   will get problems with the consistency check as then the YAML output changes as soon as a new version is released.
-   For a minor version you would accordingly use the `___minor` suffix together with a range like `[v4.0,v4.1)` to get
-   the latest `v4.0` release if the action in question provides such a tag or branch.
+    ??? tip "Dealing with stale Maven cache, a.k.a. using version ranges"
+        Additionally, the name part can have the suffix `___major` or `___minor` (three leading underscores).
+        Without these suffixes if you request a version `v1.2.3`, the generated YAML will also use exactly
+        `v1.2.3` unless you use a custom version override. With the `___major` suffix, it would only write `v1`
+        to the generated YAML, with the `___minor` suffix - `v1.2`.
+
+        This is especially useful when combined with a version range. The problem with using `v1` or `v1.2` is that for
+        GitHub Actions, these are changing tags or changing branches and not static releases. In the Maven world,
+        however, a version that does not end in `-SNAPSHOT` is considered immutable and is not expected to change.
+        This means that if a new version of the action is released that adds a new input, you cannot use it easily
+        as you still have the old `v1` artifact in your Maven cache and it will not be updated usually,
+        even though the binding server provides a new binding including the added input. And even if you remove the
+        old version from the Maven cache and get a new version from the bindings server, other people might also have
+        this outdated version in their Maven cache and then fail compilation with your changes.
+
+        To mitigate this problem, you can for example use a dependency like
+        `gradle:actions__setup-gradle___major:[v3,v4)`. This will resolve to the latest `v3.x.y` version and thus
+        include any newly added inputs, but still only write `v3` to the YAML. Without the `___major` suffix
+        or a not semantically matching range like `[v3,v5)` or even `[v3,v4]`, you will get problems with the
+        consistency check as then the YAML output changes as soon as a new version is released. For a minor version
+        you would accordingly use the `___minor` suffix together with a range like `[v4.0,v4.1)` to get
+        the latest `v4.0` release if the action in question provides such a tag or branch.
+
+        !!! info
+            If an action maintainer provides pre-releases that follow certain naming conventions as documented in the
+            [Maven Documentation](https://maven.apache.org/pom.html#Version_Order_Specification), you might need to
+            adjust the upper bound. For exmple a version `v4.0-beta` is less than `v4` and thus part of the range
+            `[v3,v4)`. In such a case - or always, to be on the safe side - you might want to change the range to
+            `[v3,v4-alpha)`, as the `alpha` version is the lowest possible version in Maven semantics.
 
 3. Use the action by importing a class like `io.github.typesafegithub.workflows.actions.actions.Checkout`.
 

jit-binding-server/src/main/kotlin/io/github/typesafegithub/workflows/jitbindingserver/ActionCoords.kt

@@ -17,7 +17,7 @@ fun Parameters.extractActionCoords(extractVersion: Boolean): ActionCoords {
             ?.let { significantVersionString ->
                 SignificantVersion
                     .entries
-                    .find { it.name.lowercase() == significantVersionString }
+                    .find { "$it" == significantVersionString }
             } ?: FULL
     val nameAndPathParts = nameAndPath.split("__")
     val name = nameAndPathParts.first()

maven-binding-builder/src/main/kotlin/io/github/typesafegithub/workflows/mavenbinding/ActionCoordsUtils.kt

@@ -5,5 +5,5 @@ import io.github.typesafegithub.workflows.actionbindinggenerator.domain.Signific
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.subName
 
 internal val ActionCoords.mavenName: String get() = "$name${subName.replace("/", "__")}${
-    significantVersion.takeUnless { it == FULL }?.let { "___${it.name.lowercase()}" } ?: ""
+    significantVersion.takeUnless { it == FULL }?.let { "___$it" } ?: ""
 }"

mkdocs.yml

@@ -24,6 +24,7 @@ theme:
         name: Switch to light mode
 
 markdown_extensions:
+  - pymdownx.details
   - pymdownx.magiclink
   - pymdownx.inlinehilite
   - pymdownx.superfences