Skip to content

Commit 05dc8f6

Browse files
krzema12krzema12
authored
docs: add migration guide for Maven-based bindings (#1372)
Part of #1318.
1 parent 1b9a7bf commit 05dc8f6

File tree

2 files changed

+113
-0
lines changed

2 files changed

+113
-0
lines changed

‎docs/user-guide/migrating-to-Maven-based-bindings.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Migrating to Maven-based bindings
2+
3+
!!! warning "Experimental"
4+
This feature is experimental. We're awaiting feedback and fixing remaining issues. Breaking changes may appear as
5+
well. You can give it a try in non-critical projects.
6+
7+
## Goal
8+
9+
Let's say you have the following workflow:
10+
11+
```kotlin
12+
#!/usr/bin/env kotlin
13+
@file:DependsOn("io.github.typesafegithub:github-workflows-kt:<newest-version>")
14+
15+
import io.github.typesafegithub.workflows.actions.actions.CheckoutV4
16+
import io.github.typesafegithub.workflows.actions.actions.SetupJavaV3
17+
import io.github.typesafegithub.workflows.actions.gradle.ActionsSetupGradleV3
18+
import io.github.typesafegithub.workflows.domain.RunnerType.UbuntuLatest
19+
import io.github.typesafegithub.workflows.domain.triggers.PullRequest
20+
import io.github.typesafegithub.workflows.dsl.workflow
21+
import io.github.typesafegithub.workflows.yaml.writeToFile
22+
23+
workflow(
24+
name = "Build",
25+
on = listOf(PullRequest()),
26+
sourceFile = __FILE__.toPath(),
27+
) {
28+
job(id = "build", runsOn = UbuntuLatest) {
29+
uses(action = CheckoutV4())
30+
uses(action = SetupJavaV3())
31+
uses(action = ActionsSetupGradleV3())
32+
run(
33+
name = "Build",
34+
command = "./gradlew build",
35+
)
36+
}
37+
}.writeToFile()
38+
```
39+
40+
`CheckoutV4`, `SetupJavaV3` and `ActionsSetupGradleV3` come with the library - they are shipped together with the DSL.
41+
It has a number of downsides:
42+
43+
* the library needs to be aware of a certain action, which requires the maintainer's attention
44+
* getting new versions of the bindings happens is tied to the release cadence of the library, which is currently
45+
released monthly
46+
* automatic updates via dependency update bots like Renovate or Dependabot aren't possible
47+
48+
We're going to switch to the new approach where each type-safe action binding is compiled and packaged in a JAR on
49+
demand, and is then shipped as a separate Maven artifact from a custom Maven-compatible server.
50+
51+
## Required changes
52+
53+
The following changes are required in our example workflow:
54+
```diff
55+
#!/usr/bin/env kotlin
56+
+ @file:Repository("https://repo1.maven.org/maven2/")
57+
@file:DependsOn("io.github.typesafegithub:github-workflows-kt:<newest-version>")
58+
+ @file:Repository("https://github-workflows-kt-bindings.colman.com.br/binding/")
59+
+ @file:DependsOn("actions:checkout:v4")
60+
+ @file:DependsOn("actions:setup-java:v3")
61+
+ @file:DependsOn("gradle:actions__setup-gradle:v3")
62+
63+
- import io.github.typesafegithub.workflows.actions.actions.CheckoutV4
64+
+ import io.github.typesafegithub.workflows.actions.actions.Checkout
65+
- import io.github.typesafegithub.workflows.actions.actions.SetupJavaV3
66+
+ import io.github.typesafegithub.workflows.actions.actions.SetupJava
67+
- import io.github.typesafegithub.workflows.actions.gradle.ActionsSetupGradleV3
68+
+ import io.github.typesafegithub.workflows.actions.gradle.ActionsSetupGradle
69+
import io.github.typesafegithub.workflows.domain.RunnerType.UbuntuLatest
70+
import io.github.typesafegithub.workflows.domain.triggers.PullRequest
71+
import io.github.typesafegithub.workflows.dsl.workflow
72+
import io.github.typesafegithub.workflows.yaml.writeToFile
73+
74+
workflow(
75+
name = "Build",
76+
on = listOf(PullRequest()),
77+
sourceFile = __FILE__.toPath(),
78+
) {
79+
job(id = "build", runsOn = UbuntuLatest) {
80+
- uses(action = CheckoutV4())
81+
+ uses(action = Checkout())
82+
- uses(action = SetupJavaV3())
83+
+ uses(action = SetupJava())
84+
- uses(action = ActionsSetupGradleV3())
85+
+ uses(action = ActionsSetupGradle())
86+
run(
87+
name = "Build",
88+
command = "./gradlew build",
89+
)
90+
}
91+
}.writeToFile()
92+
```
93+
94+
Then regenerate your YAML to ensure there are no changes.
95+
96+
## Remarks
97+
98+
1. Top-level actions like `actions/checkout@v4` map to Maven artifacts like `actions:checkout:v4`. Nested actions like
99+
`gradle/actions/setup-gradle@v3` require replacing the slash in the middle of the compound name with `__` (double
100+
underscore) because slash is not allowed in Maven coordinates. Hence, we get `gradle:actions__setup-gradle:v3`.
101+
1. So far, only major versions (e.g. `v3`) are supported. Support for full versions like `v1.2.3` will be added in the
102+
future.
103+
1. If a given binding has incorrect typing, please either ask the action owner to onboard
104+
[github-action-typing](https://github.com/typesafegithub/github-actions-typing/), or if it's not possible, contribute
105+
to [github-actions-typing-catalog](https://github.com/typesafegithub/github-actions-typing-catalog).
106+
1. The bindings server currently caches the artifacts for a given owner/name/version tuple for 1 hour
107+
([code](https://github.com/typesafegithub/github-workflows-kt/blob/1b9a7bf03982a33fc82cbc57cb41cb6ebd4c1f1b/jit-binding-server/src/main/kotlin/io/github/typesafegithub/workflows/jitbindingserver/Main.kt#L26)).
108+
If you think it's too much/too little, or a different caching strategy would be better, please reach out via GitHub
109+
issues!
110+
1. Regarding dependency update bots, Renovate is able to put updates to the Kotlin script and the YAML in a single PR,
111+
like [here](https://github.com/LeoColman/Petals/pull/510/files). It wasn't tested with Dependabot yet, feel free to
112+
give it a try!

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ nav:
4949
- Using actions: 'user-guide/using-actions.md'
5050
- Type-safe expressions: 'user-guide/type-safe-expressions.md'
5151
- Job outputs: 'user-guide/job-outputs.md'
52+
- Migrating to Maven-based bindings: 'user-guide/migrating-to-Maven-based-bindings.md'
5253
- Compensating library's missing features: 'user-guide/compensating-librarys-missing-features.md'
5354
- Nightly builds: 'user-guide/nightly-builds.md'
5455
- Feature coverage: 'feature-coverage.md'

0 commit comments

Comments
 (0)