@zio.dev/zio-sbt 0.7.1 → 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 +63 -8
  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.1")
16
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.1")
17
- addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.7.1")
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`
@@ -88,6 +103,20 @@ ZIO SBT Website is an SBT plugin that has the following tasks:
88
103
  - `sbt publishToNpm`— publishes documentation inside the `docs` directory to the npm registry.
89
104
  - `sbt generateReadme`— generate README.md file from `docs/index.md` and sbt setting keys.
90
105
 
106
+ `website/docs` is generated output, not source. `mdocOut` points there, so `compileDocs` — and
107
+ anything that sequences it, including `generateReadme` — writes compiled documentation into it.
108
+ Add it to `.gitignore`:
109
+
110
+ ```gitignore
111
+ /website/docs
112
+ /website/build
113
+ /website/node_modules
114
+ /website/.docusaurus
115
+ ```
116
+
117
+ Committing `website/docs` leaves a `website` directory that holds generated output but no
118
+ Docusaurus scaffold, and `buildWebsite` then has no `package.json` to install from.
119
+
91
120
  ## ZIO SBT CI Plugin
92
121
 
93
122
  ZIO SBT CI is an sbt plugin which generates a GitHub workflow for a project, making it easier to set up continuous integration (CI) pipelines for Scala projects. With this plugin, developers can streamline their development workflow by automating the testing and deployment process, reducing manual effort and errors. The plugin is designed to work seamlessly with sbt, the popular build tool for Scala projects, and integrates smoothly with GitHub Actions, the CI/CD platform provided by GitHub.
@@ -101,7 +130,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
101
130
  To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
102
131
 
103
132
  ```scala
104
- addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.7.1")
133
+ addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.0")
105
134
 
106
135
  resolvers ++= Resolver.sonatypeOssRepos("public")
107
136
  ```
@@ -167,6 +196,31 @@ The default value mirrors the bots used by the `zio/zio` repository: `Seq(Depend
167
196
  >
168
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.
169
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
+
170
224
  ### Keeping the Workflow in Sync
171
225
 
172
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:
@@ -193,6 +247,7 @@ All settings are `ThisBuild`-scoped.
193
247
  | `ciConcurrency` | `Option[Concurrency]` | one run per branch, cancelling in progress | Concurrency group, or `None` to omit the block |
194
248
  | `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
195
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 |
196
251
 
197
252
  **Test matrix**
198
253
 
@@ -235,7 +290,7 @@ All settings are `ThisBuild`-scoped.
235
290
 
236
291
  | Task | Description |
237
292
  | --- | --- |
238
- | `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` |
239
294
  | `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
240
295
  | `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
241
296
  | `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
@@ -380,7 +435,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
380
435
  Add the following line to your `libraryDependencies` in `build.sbt`:
381
436
 
382
437
  ```scala
383
- libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.7.1"
438
+ libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.0"
384
439
  ```
385
440
 
386
441
  ### Features
@@ -513,7 +568,7 @@ test:
513
568
  with:
514
569
  fetch-depth: '0'
515
570
  - name: Test
516
- run: sbt +test
571
+ run: sbt --no-colors +test
517
572
  ```
518
573
 
519
574
  The `sbt +test` command will run the `test` task for all submodules in the project against all Scala versions defined in the `crossScalaVersions` setting.
@@ -582,5 +637,5 @@ test:
582
637
  with:
583
638
  fetch-depth: '0'
584
639
  - name: Test
585
- run: sbt ${{ matrix.scala-project }}/test
640
+ run: sbt --no-colors ${{ matrix.scala-project }}/test
586
641
  ```
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.1",
5
+ "version": "0.8.0",
6
6
  "repository": {
7
7
  "url": "https://github.com/zio/zio-sbt"
8
8
  }