@zio.dev/zio-sbt 0.6.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/.gitkeep +0 -0
  2. package/index.md +228 -16
  3. package/package.json +1 -1
package/.gitkeep ADDED
File without changes
package/index.md CHANGED
@@ -5,16 +5,16 @@ title: "ZIO SBT"
5
5
 
6
6
  _ZIO SBT_ contains multiple sbt plugins that are useful for ZIO projects. It provides high-level SBT utilities that simplify the development of ZIO applications.
7
7
 
8
- [![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-sbt/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-sbt-website_2.12.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-sbt-website_2.12/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-sbt-website_2.12.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-sbt-website_2.12/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-sbt-docs_2.12/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-sbt-docs_2.12) [![ZIO SBT](https://img.shields.io/github/stars/zio/zio-sbt?style=social)](https://github.com/zio/zio-sbt)
8
+ [![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-sbt/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/maven-central/v/dev.zio/zio-sbt-website_2.12_1.0.svg?label=Sonatype%20Release)](https://central.sonatype.com/artifact/dev.zio/zio-sbt-website_2.12_1.0) [![Sonatype Snapshots](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fcentral.sonatype.com%2Frepository%2Fmaven-snapshots%2Fdev%2Fzio%2Fzio-sbt-website_2.12_1.0%2Fmaven-metadata.xml&label=Sonatype%20Snapshot)](https://central.sonatype.com/repository/maven-snapshots/dev/zio/zio-sbt-website_2.12_1.0/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-sbt-website_2.12_1.0/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-sbt-website_2.12_1.0) [![ZIO SBT](https://img.shields.io/github/stars/zio/zio-sbt?style=social)](https://github.com/zio/zio-sbt)
9
9
 
10
10
  ## Installation
11
11
 
12
12
  Add the following lines to your `project/plugins.sbt` file:
13
13
 
14
14
  ```scala
15
- addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.6.3")
16
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.6.3")
17
- addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.6.3")
15
+ addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.7.0")
16
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.0")
17
+ addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.7.0")
18
18
  ```
19
19
 
20
20
  Then you can enable them by using the following code in your `build.sbt` file:
@@ -101,7 +101,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
101
101
  To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
102
102
 
103
103
  ```scala
104
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.6.3")
104
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.0")
105
105
 
106
106
  resolvers ++= Resolver.sonatypeOssRepos("public")
107
107
  ```
@@ -118,12 +118,20 @@ Now you can generate a Github workflow by running the following command:
118
118
  sbt ciGenerateGithubWorkflow
119
119
  ```
120
120
 
121
- This will generate a GitHub workflow file inside the `.github/workflows` directory, named `ci.yml`. The workflow file contains following default Jobs:
121
+ This will generate a GitHub workflow file inside the `.github/workflows` directory, named `ci.yml`. The workflow file contains the following default jobs:
122
122
 
123
- - Build
124
- - Lint
125
- - Test
126
- - Update Readme
123
+ | Job | What it does |
124
+ | --- | --- |
125
+ | `build` | Compiles everything, publishes locally, and builds the website |
126
+ | `lint` | Checks the generated workflow is up to date, then runs `sbt lint` |
127
+ | `test` | Runs the test suite across the target Java versions |
128
+ | `update-readme` | Regenerates `README.md` from `docs/index.md` and opens a PR |
129
+ | `ci` | Aggregate gate: succeeds only if the jobs above did. Point branch protection at this one |
130
+ | `release` | Runs `sbt ci-release` on a published release, and on pushes to enabled branches for SNAPSHOTs |
131
+ | `release-docs` | Publishes the docs to npm |
132
+ | `notify-docs-release` | Tells `zio/zio` to rebuild the docs site |
133
+
134
+ Note that the plugin declares `trigger = allRequirements`, so having it on the classpath is enough — `enablePlugins(ZioSbtCiPlugin)` is not strictly required. Its settings are defined at `ThisBuild` level, so set them as `ThisBuild / ciSomething := ...`, or inside `inThisBuild(...)`.
127
135
 
128
136
  > **Note:**
129
137
  >
@@ -159,6 +167,210 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
159
167
  >
160
168
  > For `gh pr merge --auto` to actually merge a PR (rather than just queue it), the target repository needs "Allow auto-merge" enabled under **Settings → General**, and branch protection with required status checks configured on the target branch.
161
169
 
170
+ ### Keeping the Workflow in Sync
171
+
172
+ The generated files are meant to be committed and never edited by hand. To stop them drifting from the build, run the check in CI — the default `lint` job already does:
173
+
174
+ ```bash
175
+ sbt ciCheckGithubWorkflow
176
+ ```
177
+
178
+ It regenerates the workflows and fails if the result differs from what is committed, naming the files that are stale. If a generated file is edited directly, the next run of this check fails, which is what keeps `build.sbt` the single source of truth.
179
+
180
+ ### Settings Reference
181
+
182
+ All settings are `ThisBuild`-scoped.
183
+
184
+ **Workflow-level**
185
+
186
+ | Setting | Type | Default | Description |
187
+ | --- | --- | --- | --- |
188
+ | `ciWorkflowTitle` | `String` | `"CI"` | Workflow name, lowercased to form the filename (`ci.yml`). Named this way to avoid colliding with zio-sbt-website's `ciWorkflowName`, which sets the README badge |
189
+ | `ciEnabledBranches` | `Seq[String]` | `Seq.empty` | Branches the workflow runs on. Empty means every branch |
190
+ | `ciWorkflowEnv` | `Map[String, String]` | derived from `ciJvmOptions`/`ciNodeOptions` | Workflow-level environment. Assigning **replaces** the derived map, which is how a build opts out of `JDK_JAVA_OPTIONS` |
191
+ | `ciJvmOptions` | `Seq[String]` | `Seq.empty` | Appended to `JDK_JAVA_OPTIONS` |
192
+ | `ciNodeOptions` | `Seq[String]` | `Seq.empty` | Sets `NODE_OPTIONS` when non-empty |
193
+ | `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
194
+ | `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
195
+ | `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
196
+
197
+ **Test matrix**
198
+
199
+ | Setting | Type | Default | Description |
200
+ | --- | --- | --- | --- |
201
+ | `ciTargetJavaVersions` | `Seq[String]` | `Seq("17", "21", "25")` | Java versions in the test matrix |
202
+ | `ciDefaultJavaVersion` | `String` | `"17"` | Java version for the non-matrix jobs |
203
+ | `ciTargetScalaVersions` | `Map[String, Seq[String]]` | `Map.empty` | Module to Scala versions. Empty runs a plain `sbt +test` |
204
+ | `ciTargetMinJavaVersions` | `Map[String, String]` | `Map.empty` | Module to minimum Java version, gating modules per matrix entry |
205
+ | `ciGroupSimilarTests` | `Boolean` | `false` | Groups by Java and Scala version instead of one entry per module |
206
+ | `ciMatrixMaxParallel` | `Option[Int]` | `None` | `strategy.max-parallel` |
207
+
208
+ **Jobs and steps**
209
+
210
+ | Setting | Type | Default | Description |
211
+ | --- | --- | --- | --- |
212
+ | `ciBuildJobs` | `Seq[Job]` | one `build` job | Replaces or extends the build jobs |
213
+ | `ciLintJobs` | `Seq[Job]` | one `lint` job | |
214
+ | `ciTestJobs` | `Seq[Job]` | one `test` job | |
215
+ | `ciUpdateReadmeJobs` | `Seq[Job]` | one `update-readme` job | Set to `Seq.empty` if the README is maintained by hand |
216
+ | `ciReleaseJobs` | `Seq[Job]` | one `release` job | |
217
+ | `ciPostReleaseJobs` | `Seq[Job]` | `release-docs`, `notify-docs-release` | |
218
+ | `ciPullRequestApprovalJobs` | `Seq[String]` | the ids of `ciLintJobs`, `ciTestJobs` and `ciBuildJobs` | Job ids the aggregate `ci` job waits on. Follows the jobs those three settings produce, so renaming or adding one is picked up without touching this |
219
+ | `ciReleaseApprovalJobs` | `Seq[String]` | `Seq("ci")` | Job ids the release waits on |
220
+ | `ciCheckArtifactsCompilationSteps` | `Seq[Step]` | `sbt +Test/compile` | |
221
+ | `ciCheckArtifactsBuildSteps` | `Seq[Step]` | `sbt +publishLocal` | |
222
+ | `ciCheckWebsiteBuildProcess` | `Seq[Step]` | `sbt docs/buildWebsite` | Set to `Seq.empty` in a build with no `docs` project |
223
+ | `ciCheckGithubWorkflowSteps` | `Seq[Step]` | `sbt ciCheckGithubWorkflow` | |
224
+
225
+ **Release and docs**
226
+
227
+ | Setting | Type | Default | Description |
228
+ | --- | --- | --- | --- |
229
+ | `ciPublishSnapshots` | `Boolean` | `true` | Also publish SNAPSHOTs on pushes to enabled branches |
230
+ | `ciUpdateReadmeCondition` | `Option[Condition]` | `None` | When to run the README job. Defaults to published releases |
231
+ | `ciDocsVersioningScheme` | `DocsVersioning` | `SemanticVersioning` | `SemanticVersioning` or `HashVersioning` |
232
+ | `ciDependencyUpdateBots` | `Seq[DependencyBot]` | Dependabot, Renovate, `ScalaSteward("zio-scala-steward")` | Bots whose PRs are auto-approved and auto-merged |
233
+
234
+ **Tasks**
235
+
236
+ | Task | Description |
237
+ | --- | --- |
238
+ | `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml` |
239
+ | `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
240
+ | `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
241
+ | `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
242
+
243
+ ### Customizing Jobs
244
+
245
+ Jobs are values, so they can be transformed or replaced. The types live in `zio.sbt.githubactions` and the reusable steps in `zio.sbt.ZioSbtCiPlugin`; neither is exported through `autoImport`, so import them explicitly.
246
+
247
+ To adjust the generated jobs, map over them:
248
+
249
+ ```scala
250
+ import zio.sbt.githubactions.Job
251
+
252
+ def onUbuntu22(job: Job): Job = job.copy(runsOn = "ubuntu-22.04")
253
+
254
+ inThisBuild(
255
+ List(
256
+ ciTestJobs := ciTestJobs.value.map(onUbuntu22),
257
+ ciBuildJobs := ciBuildJobs.value.map(onUbuntu22)
258
+ )
259
+ )
260
+ ```
261
+
262
+ To write one from scratch, build it from the exported steps:
263
+
264
+ ```scala
265
+ import zio.sbt.ZioSbtCiPlugin._
266
+ import zio.sbt.githubactions.{Job, Step, Strategy}
267
+
268
+ ciTestJobs := Seq(
269
+ Job(
270
+ id = "integration-test",
271
+ name = "Integration Test",
272
+ jobTimeout = Some(30),
273
+ strategy = Some(Strategy(matrix = Map("java" -> List("17", "21")), failFast = false)),
274
+ steps = Seq(
275
+ Checkout.value,
276
+ SetupJava("17"),
277
+ SetupSBT,
278
+ CacheDependencies,
279
+ Step.SingleStep(name = "Test", run = Some("sbt it:test"))
280
+ )
281
+ )
282
+ )
283
+ ```
284
+
285
+ The aggregate `ci` job waits on the ids of whatever `ciLintJobs`, `ciTestJobs` and `ciBuildJobs`
286
+ produce, so replacing `test` with `integration-test` above is enough on its own. Set
287
+ `ciPullRequestApprovalJobs` only to wait on a different set than those three:
288
+
289
+ ```scala
290
+ ciPullRequestApprovalJobs := Seq("lint", "integration-test")
291
+ ```
292
+
293
+ `Checkout`, `SetupLibuv`, `SetupJava(version)`, `SetupSBT`, `CacheDependencies`, `SetupNodeJs` and `SetSwapSpace` are all available; the ones defined as settings need `.value`.
294
+
295
+ ### Job Timeouts
296
+
297
+ A job with no timeout inherits GitHub's default of six hours, which is a long time to wait for a hung build:
298
+
299
+ ```scala
300
+ Job(id = "test", name = "Test", jobTimeout = Some(25), steps = ...)
301
+
302
+ // or on an existing job
303
+ ciTestJobs := ciTestJobs.value.map(_.withTimeout(25))
304
+ ```
305
+
306
+ > **Note:**
307
+ >
308
+ > `Job` also has an older `timeoutMinutes: Int` field. It predates `jobTimeout` and was accepted but never rendered, so it is deprecated. It is still honoured when set to anything other than its historical default of `30`, so builds that set it keep working.
309
+
310
+ ### Concurrency
311
+
312
+ By default one run per branch is kept and in-progress runs are cancelled. `cancelInProgress` accepts an expression as well as a boolean, which is what lets a workflow cancel superseded pull request runs while letting releases finish:
313
+
314
+ ```scala
315
+ import zio.sbt.githubactions.{CancelInProgress, Concurrency, Condition}
316
+
317
+ ciConcurrency := Some(
318
+ Concurrency(
319
+ group = "ci-pr-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }}",
320
+ cancelInProgress = CancelInProgress.When(Condition.Expression("github.event_name == 'pull_request'"))
321
+ )
322
+ )
323
+ ```
324
+
325
+ Individual jobs can override it. A release should generally not be cancelled halfway through:
326
+
327
+ ```scala
328
+ Job(
329
+ id = "release",
330
+ name = "Release",
331
+ concurrency = Some(
332
+ Concurrency(group = "release-${{ github.ref }}", cancelInProgress = CancelInProgress.Never)
333
+ ),
334
+ steps = ...
335
+ )
336
+ ```
337
+
338
+ ### Service Containers
339
+
340
+ Jobs that need a database can attach a service. `options` carries the raw `docker create` arguments, which is where the health check goes — without one the job races the container and steps can start before it accepts connections:
341
+
342
+ ```scala
343
+ import zio.Chunk
344
+ import zio.sbt.githubactions.{ImageRef, Service, ServicePort}
345
+
346
+ Job(
347
+ id = "test",
348
+ name = "Test",
349
+ services = Seq(
350
+ Service(
351
+ name = "postgres",
352
+ image = ImageRef("postgres:16"),
353
+ env = Map("POSTGRES_USER" -> "postgres", "POSTGRES_PASSWORD" -> "postgres"),
354
+ ports = Chunk(ServicePort(5432, 5432)),
355
+ options = Some("--health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5")
356
+ )
357
+ ),
358
+ steps = ...
359
+ )
360
+ ```
361
+
362
+ `ServicePort(inner, outer)` renders as `inner:outer`, which GitHub reads as `<host>:<container>` — so `inner` is the port a step connects to on `localhost`.
363
+
364
+ ### The Workflow Environment
365
+
366
+ By default the workflow exports `JDK_JAVA_OPTIONS`, built from `ciJvmOptions`. That is not always wanted: it makes `java -version` print a note containing commas, which corrupts the cache keys computed by `setup-sbt` and `coursier/cache-action`. Assigning `ciWorkflowEnv` replaces the derived map, so JVM flags can go through `SBT_OPTS` instead:
367
+
368
+ ```scala
369
+ ciWorkflowEnv := Map(
370
+ "SBT_OPTS" -> "-XX:+PrintCommandLineFlags -Djava.locale.providers=CLDR,JRE"
371
+ )
372
+ ```
373
+
162
374
  ## ZIO SBT Source
163
375
 
164
376
  ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides utilities for self-documenting example code. It includes the `ExprEval` macro, which captures the source text of expressions at compile time and prints them alongside their evaluated results at runtime.
@@ -168,7 +380,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
168
380
  Add the following line to your `libraryDependencies` in `build.sbt`:
169
381
 
170
382
  ```scala
171
- libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.6.3"
383
+ libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.7.0"
172
384
  ```
173
385
 
174
386
  ### Features
@@ -274,7 +486,7 @@ Both forms emit `showLineNumbers` in the code fence header, enabling line number
274
486
 
275
487
  ### Default Testing Strategy
276
488
 
277
- The default testing strategy for ZIO SBT CI plugin is to run `sbt +test` on Corretto Java 11, 17 and 21. So this will generate the following job:
489
+ The default testing strategy for ZIO SBT CI plugin is to run `sbt +test` on Corretto Java 17, 21 and 25. So this will generate the following job:
278
490
 
279
491
  ```yaml
280
492
  test:
@@ -284,12 +496,12 @@ test:
284
496
  strategy:
285
497
  fail-fast: false
286
498
  matrix:
287
- java: ['11', '17', '21']
499
+ java: ['17', '21', '25']
288
500
  steps:
289
501
  - name: Install libuv
290
502
  run: sudo apt-get update && sudo apt-get install -y libuv1-dev
291
503
  - name: Setup Scala
292
- uses: actions/setup-java@v3.13.0
504
+ uses: actions/setup-java@v5
293
505
  with:
294
506
  distribution: corretto
295
507
  java-version: ${{ matrix.java }}
@@ -348,7 +560,7 @@ test:
348
560
  strategy:
349
561
  fail-fast: false
350
562
  matrix:
351
- java: ['11', '17', '21']
563
+ java: ['17', '21', '25']
352
564
  scala-project:
353
565
  - ++2.12.20 submoduleA
354
566
  - ++2.12.20 submoduleB
@@ -358,7 +570,7 @@ test:
358
570
  - name: Install libuv
359
571
  run: sudo apt-get update && sudo apt-get install -y libuv1-dev
360
572
  - name: Setup Scala
361
- uses: actions/setup-java@v3.10.0
573
+ uses: actions/setup-java@v5
362
574
  with:
363
575
  distribution: corretto
364
576
  java-version: ${{ matrix.java }}
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@zio.dev/zio-sbt",
3
3
  "description": "ZIO SBT Documentation",
4
4
  "license": "Apache-2.0",
5
- "version": "0.6.3",
5
+ "version": "0.7.0",
6
6
  "repository": {
7
7
  "url": "https://github.com/zio/zio-sbt"
8
8
  }