@zio.dev/zio-sbt 0.7.2 → 0.8.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 (2) hide show
  1. package/index.md +47 -6
  2. package/package.json +1 -1
package/index.md CHANGED
@@ -12,9 +12,9 @@ _ZIO SBT_ contains multiple sbt plugins that are useful for ZIO projects. It pro
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.7.2")
16
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.2")
17
- addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.7.2")
15
+ addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.0")
16
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.0")
17
+ addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.0")
18
18
  ```
19
19
 
20
20
  Then you can enable them by using the following code in your `build.sbt` file:
@@ -60,6 +60,21 @@ There are also some other settings that are useful for configuring the projects:
60
60
  - `enableZIO`- a set of ZIO related settings such as enabling zio streams and ZIO test framework.
61
61
  - `jsSettings`, `nativeSettings`- common platform specific settings for Scala.js and Scala Native.
62
62
 
63
+ `enableZIO` adds ZIO as a dependency using the `zioVersion` setting, which the plugin gives a
64
+ default value to. Always override it explicitly in your own `build.sbt`:
65
+
66
+ ```scala
67
+ ThisBuild / zioVersion := "2.1.22"
68
+ ```
69
+
70
+ :::note
71
+ Don't rely on `zioVersion`'s default. It's baked into whichever version of zio-sbt-ecosystem you
72
+ depend on, so upgrading the plugin—including via an automated dependency-update PR—can silently
73
+ change your project's own ZIO version along with it. Setting `zioVersion` explicitly keeps that a
74
+ deliberate decision you make, not a side effect of a plugin bump. Every ZIO ecosystem project
75
+ (zio-logging, zio-kafka, zio-cache, and others) already follows this practice.
76
+ :::
77
+
63
78
  It also provides some helper methods that are useful for configuring a compiler option for a specific Scala version:
64
79
 
65
80
  - `optionsOn`
@@ -115,7 +130,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
115
130
  To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
116
131
 
117
132
  ```scala
118
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.2")
133
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.0")
119
134
 
120
135
  resolvers ++= Resolver.sonatypeOssRepos("public")
121
136
  ```
@@ -181,6 +196,31 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
181
196
  >
182
197
  > 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.
183
198
 
199
+ > **Note:**
200
+ >
201
+ > `GITHUB_TOKEN` can never be granted the "workflows" scope needed to auto-merge a bot PR that touches `.github/workflows/**`, so `auto-merge.yml` mints a GitHub App token for that case instead, falling back to `GITHUB_TOKEN` when no app is configured (which still auto-merges ordinary, non-workflow-touching PRs fine). This needs the same `APP_ID`/`APP_PRIVATE_KEY` secrets as `update-readme`, and the [ZIO Assistant](https://github.com/apps/zio-assistant) app installation must additionally have the **Workflows** repository permission granted and accepted — without it, workflow-touching PRs still fail to auto-merge and need a manual merge.
202
+
203
+ ### Netlify Deploy Previews
204
+
205
+ Setting `ciEnableDeployPreview := true` makes `ciGenerateGithubWorkflow` also generate `deploy-preview.yml`, which deploys the built Docusaurus site to Netlify for every pull request that touches `docs/` or `website/`.
206
+
207
+ ```scala
208
+ ThisBuild / ciEnableDeployPreview := true
209
+ ```
210
+
211
+ The feature is split across two workflows, decoupled by artifacts rather than triggering the deploy directly from a pull request event:
212
+
213
+ - The `build` job gains a few extra steps. `Check website is installed` runs first, checking that `website/package.json` and `website/docusaurus.config.js` both exist — the same signal [`installWebsite`](#zio-sbt-website) itself uses to tell a real Docusaurus scaffold apart from a `website/` directory holding only `mdocOut`'s generated output. Only when the website is installed does the job go on to detect whether the pull request touched `docs/` or `website/`, and if so upload `website/build` as a `website-artifact`, plus the PR number as a `pr-metadata` artifact.
214
+ - `deploy-preview.yml` triggers on `workflow_run` once the CI workflow completes, downloads those two artifacts, deploys `website-artifact` to Netlify with [`nwtgck/actions-netlify`](https://github.com/nwtgck/actions-netlify) under a deterministic `pr-<number>` alias — so the preview URL for a given PR is stable across redeploys, of the shape `pr-<number>--<your-netlify-site-name>.netlify.app` — then posts a fresh comment with the preview URL via [`peter-evans/create-or-update-comment`](https://github.com/peter-evans/create-or-update-comment) — each deploy gets its own comment rather than editing one in place, so pushing a follow-up commit doesn't erase the record of the previous deploy. Earlier preview comments (tagged with an `<!-- netlify-preview-comment -->` marker) are collapsed as outdated first, via [`actions/github-script`](https://github.com/actions/github-script), so the thread doesn't accumulate clutter — the whole comment history is paginated through, not just the first page, so this still works on pull requests with a long comment history.
215
+
216
+ Using `workflow_run` instead of triggering directly on `pull_request` means the deploy step only ever runs after CI has actually succeeded, and it runs with read/write access to secrets even for pull requests from forks (where a plain `pull_request` trigger would not have that access).
217
+
218
+ `deploy-preview.yml` triggers on *every* successful pull-request CI run, not only the ones where `build` actually uploaded artifacts — a PR that doesn't touch `docs/`/`website/`, or a repo with no website installed yet, never produces `website-artifact`/`pr-metadata` at all. To handle that, the two `actions/download-artifact` steps set `continue-on-error: true`, since a missing artifact there is an expected outcome, not a failure worth stopping the job over; every step after them then checks `steps.download-website.outcome == 'success' && steps.download-pr-metadata.outcome == 'success'` before running. So a run with nothing to deploy ends with two soft-failed downloads and nothing else — no deploy call, no PR comment — instead of a hard job failure.
219
+
220
+ Put together, this makes `ciEnableDeployPreview` safe to turn on before the Docusaurus site exists: neither workflow does any real work until `website/` is a genuine installation and a pull request actually changes it.
221
+
222
+ This requires two repository secrets: `NETLIFY_AUTH_TOKEN`, a [personal access token](https://docs.netlify.com/api/get-started/#authentication) generated from the Netlify user account that owns the site, and `NETLIFY_SITE_ID`, found under the site's **Site configuration → General → Site details** in the Netlify dashboard. The default value of `ciEnableDeployPreview` is `false`, so existing builds see no change until they opt in.
223
+
184
224
  ### Keeping the Workflow in Sync
185
225
 
186
226
  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:
@@ -207,6 +247,7 @@ All settings are `ThisBuild`-scoped.
207
247
  | `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
208
248
  | `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
209
249
  | `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
250
+ | `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
210
251
 
211
252
  **Test matrix**
212
253
 
@@ -249,7 +290,7 @@ All settings are `ThisBuild`-scoped.
249
290
 
250
291
  | Task | Description |
251
292
  | --- | --- |
252
- | `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml` |
293
+ | `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml`, plus `deploy-preview.yml` when `ciEnableDeployPreview` is `true` |
253
294
  | `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
254
295
  | `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
255
296
  | `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
@@ -394,7 +435,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
394
435
  Add the following line to your `libraryDependencies` in `build.sbt`:
395
436
 
396
437
  ```scala
397
- libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.7.2"
438
+ libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.0"
398
439
  ```
399
440
 
400
441
  ### Features
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.7.2",
5
+ "version": "0.8.0",
6
6
  "repository": {
7
7
  "url": "https://github.com/zio/zio-sbt"
8
8
  }