@zio.dev/zio-sbt 0.8.10 → 0.8.11
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.
- package/concepts/generated-files.md +22 -0
- package/concepts/how-the-plugins-fit-together.md +29 -0
- package/concepts/index.md +10 -0
- package/getting-started.md +91 -0
- package/how-to-guides/add-a-service-container-to-a-job.md +28 -0
- package/how-to-guides/auto-approve-and-auto-merge-dependency-update-prs.md +36 -0
- package/how-to-guides/build-a-workflow-of-only-custom-jobs.md +15 -0
- package/how-to-guides/change-the-workflow-environment.md +12 -0
- package/how-to-guides/configure-dependabot-updates.md +24 -0
- package/how-to-guides/configure-scala-steward.md +16 -0
- package/how-to-guides/control-ci-concurrency.md +30 -0
- package/how-to-guides/customize-the-generated-ci-jobs.md +54 -0
- package/how-to-guides/customize-the-generated-readme.md +36 -0
- package/how-to-guides/draft-releases-with-release-drafter.md +16 -0
- package/how-to-guides/enable-netlify-deploy-previews.md +42 -0
- package/how-to-guides/keep-the-workflow-in-sync.md +12 -0
- package/how-to-guides/publish-a-releases-docs-again.md +18 -0
- package/how-to-guides/regenerate-workflows-on-bot-prs.md +15 -0
- package/how-to-guides/set-job-timeouts.md +17 -0
- package/how-to-guides/test-against-several-scala-and-java-versions.md +101 -0
- package/index.md +25 -733
- package/package.json +1 -1
- package/reference/ci.md +148 -0
- package/reference/ecosystem.md +141 -0
- package/reference/githubactions.md +51 -0
- package/reference/index.md +15 -0
- package/reference/source.md +109 -0
- package/reference/website.md +103 -0
- package/sidebars.js +57 -3
- package/tutorials/set-up-a-new-zio-library.md +141 -0
package/package.json
CHANGED
package/reference/ci.md
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ci
|
|
3
|
+
title: "ZIO SBT CI"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`ZioSbtCiPlugin` generates the GitHub Actions workflows of a project from its `build.sbt`, so continuous integration (CI) is configured in one place. The default workflow builds, tests, lints and publishes the project, and every part of it can be changed with sbt settings or replaced by custom jobs. The model of workflows, jobs and steps lives in [ZIO SBT GitHub Actions](./githubactions.md).
|
|
7
|
+
|
|
8
|
+
To install the plugin, add `addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.11")` to `project/plugins.sbt`, as described in [Installation](../index.md#installation). Using SNAPSHOT versions of the plugin also needs `resolvers ++= Resolver.sonatypeOssRepos("public")`.
|
|
9
|
+
|
|
10
|
+
The plugin declares `trigger = allRequirements`, so having it on the classpath is enough, and `enablePlugins(ZioSbtCiPlugin)` is not strictly required. Its settings are defined at `ThisBuild` level, so set them as `ThisBuild / ciSomething := ...`, or inside `inThisBuild(...)`.
|
|
11
|
+
|
|
12
|
+
To use the plugin, install the [ZIO Assistant](https://github.com/apps/zio-assistant) GitHub App on the repository.
|
|
13
|
+
|
|
14
|
+
## Generated Files
|
|
15
|
+
|
|
16
|
+
`ciGenerateGithubWorkflow` writes these files. Commit them and never edit them by hand. See [Keep the Generated Workflow in Sync](../how-to-guides/keep-the-workflow-in-sync.md) to check that they match the build.
|
|
17
|
+
|
|
18
|
+
| File | Generated when |
|
|
19
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
20
|
+
| `.github/workflows/ci.yml` | Always. The file name is `ciWorkflowTitle` lower-cased, with non-alphanumeric characters turned into `-` |
|
|
21
|
+
| `.github/workflows/auto-approve.yml` | Always |
|
|
22
|
+
| `.github/workflows/auto-merge.yml` | Always |
|
|
23
|
+
| `.github/workflows/deploy-preview.yml` | `ciEnableDeployPreview` is `true` |
|
|
24
|
+
| `.github/workflows/release-drafter.yml` | `ciEnableReleaseDrafter` is `true` (the default). Scaffolds `.github/release-drafter.yml` once |
|
|
25
|
+
| `.github/workflows/scala-steward.yml` | `ciEnableScalaSteward` is `true` (the default). Scaffolds `.scala-steward.conf` once when `ciScalaStewardConfig` renders content |
|
|
26
|
+
| `.github/dependabot.yml` | `ciEnableDependabot` is `true` (the default) |
|
|
27
|
+
| `.github/workflows/regenerate-workflows.yml` | `ciEnableRegenerateWorkflows` is `true` (the default) |
|
|
28
|
+
|
|
29
|
+
## Default Jobs
|
|
30
|
+
|
|
31
|
+
The generated `ci.yml` contains these jobs:
|
|
32
|
+
|
|
33
|
+
| Job | What it does |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `build` | Compiles everything, publishes locally, and builds the website |
|
|
36
|
+
| `lint` | Checks the generated workflow is up to date, then runs `sbt lint` |
|
|
37
|
+
| `test` | Runs the test suite across the target Java versions |
|
|
38
|
+
| `update-readme` | Regenerates `README.md` from `docs/index.md` and opens a PR |
|
|
39
|
+
| `ci` | Aggregate gate: succeeds only if the jobs above did. Point branch protection at this one |
|
|
40
|
+
| `release` | Runs `sbt ci-release` on a published release or a manual run, and on pushes to the default branch for SNAPSHOTs |
|
|
41
|
+
| `release-docs` | Publishes the docs to npm after a successful `release`, or on a manual run with `docs-only` set to `true` |
|
|
42
|
+
| `notify-docs-release` | Dispatches an `update-docs` event to `zio/zio` with the docs package name and version, so the ZIO website picks up the new docs |
|
|
43
|
+
|
|
44
|
+
`notify-docs-release` takes the docs version from the release tag, or from the newest `v` tag on a manual `docs-only` run, and waits for up to five minutes until npm lists exactly that version. It fails if the version never appears. With `HashVersioning` as `ciDocsVersioningScheme`, it still reads the `latest` version with `npm view <package> version`.
|
|
45
|
+
|
|
46
|
+
The default workflow runs on `workflow_dispatch`, published releases, pushes (to `ciEnabledBranches` when set, otherwise every branch) and pull requests that do not target `gh-pages`.
|
|
47
|
+
|
|
48
|
+
## Concurrency of the Default Workflow
|
|
49
|
+
|
|
50
|
+
By default `ciConcurrency` is one run per workflow and ref, and an in-progress run is cancelled when a newer run starts in the same group. The group is `${{ github.workflow }}-${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && github.run_id || github.ref }}`. On the default branch the group ends with the run id, so every run is kept. On any other ref, including a tag such as `refs/tags/v1.9.2`, the group ends with the ref.
|
|
51
|
+
|
|
52
|
+
A release event and the push of its tag have the same ref, so they share one group, and the run that starts later cancels the earlier one. To change this, set `ciConcurrency` as described in [Control CI Concurrency](../how-to-guides/control-ci-concurrency.md).
|
|
53
|
+
|
|
54
|
+
## Settings
|
|
55
|
+
|
|
56
|
+
All settings are `ThisBuild`-scoped.
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
### Workflow-Level
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
| Setting | Type | Default | Description |
|
|
63
|
+
| --- | --- | --- | --- |
|
|
64
|
+
| `ciWorkflowTitle` | `String` | `"CI"` | Workflow name. The file name is its lower-cased form with each run of non-alphanumeric characters replaced by `-` (`ci.yml` for `CI`). Named this way to avoid colliding with zio-sbt-website's `ciWorkflowName`, which sets the README badge |
|
|
65
|
+
| `ciEnabledBranches` | `Seq[String]` | `Seq.empty` | Branches the workflow runs on. Empty means every branch |
|
|
66
|
+
| `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` |
|
|
67
|
+
| `ciJvmOptions` | `Seq[String]` | `Seq.empty` | Appended to `JDK_JAVA_OPTIONS` |
|
|
68
|
+
| `ciNodeOptions` | `Seq[String]` | `Seq.empty` | Sets `NODE_OPTIONS` when non-empty |
|
|
69
|
+
| `ciConcurrency` | `Option[Concurrency]` | one run per ref, cancelling in progress, except that every run on the default branch is kept | Concurrency group, or `None` to omit the block. See [Concurrency of the Default Workflow](#concurrency-of-the-default-workflow) |
|
|
70
|
+
| `ciWorkflowPermissions` | `Option[Map[String, String]]` | `Some(id-token: write, contents: read)` | Workflow-level `permissions`. `None` omits the block, so the workflow runs with the repository's default token permissions; `Some(Map.empty)` instead renders `permissions: {}`, which grants nothing |
|
|
71
|
+
| `ciSwapSizeGB` | `Int` | `0` | Adds a swap-space step to every job when greater than zero |
|
|
72
|
+
| `ciBackgroundJobs` | `Seq[String]` | `Seq.empty` | Commands prefixed to each `run`, for daemons a job needs |
|
|
73
|
+
| `ciEnableDeployPreview` | `Boolean` | `false` | Adds website-artifact upload steps to `build` and generates `deploy-preview.yml`. Requires `NETLIFY_AUTH_TOKEN`/`NETLIFY_SITE_ID` secrets |
|
|
74
|
+
| `ciDeployPreviewMode` | `DeployPreviewMode` | `DeployPreviewMode.Automatic` | Only used with `ciEnableDeployPreview`. `Automatic` deploys every successful pull-request CI run; `OnDemand` posts a "Deploy preview" checkbox comment and deploys only when it is ticked |
|
|
75
|
+
| `ciEnableReleaseDrafter` | `Boolean` | `true` | Generates `release-drafter.yml` and scaffolds `.github/release-drafter.yml` (once). Overwrites a hand-written `release-drafter.yml` when on; when off, only deletes a copy it generated itself |
|
|
76
|
+
| `ciReleaseDrafterCategories` | `Seq[ReleaseDrafterCategory]` | Features/Bug Fixes/Maintenance/Dependency Updates | Categories written into the scaffolded config on first generation only |
|
|
77
|
+
| `ciReleaseDrafterVersionResolver` | `Option[ReleaseDrafterVersionResolver]` | `None` | Optional `version-resolver` block for the scaffolded config |
|
|
78
|
+
| `ciReleaseDrafterAutolabeler` | `Seq[ReleaseDrafterAutolabelerRule]` | `Seq.empty` | Optional `autolabeler` rules for the scaffolded config |
|
|
79
|
+
| `ciReleaseDrafterExcludeLabels` | `Seq[String]` | `Seq("skip-changelog")` | `exclude-labels` for the scaffolded config |
|
|
80
|
+
| `ciReleaseDrafterBranch` | `Option[Branch]` | `None` | Branch `release-drafter.yml`'s `push` trigger runs on. Falls back to the first of `ciEnabledBranches`, then `"main"` |
|
|
81
|
+
| `ciEnableScalaSteward` | `Boolean` | `true` | Generates `scala-steward.yml` and scaffolds `.scala-steward.conf` (once, only if non-empty). Overwrites a hand-written `scala-steward.yml` when on; when off, only deletes a copy it generated itself |
|
|
82
|
+
| `ciScalaStewardSchedule` | `String` | `"0 0 * * *"` | Cron schedule for `scala-steward.yml`'s `schedule` trigger |
|
|
83
|
+
| `ciScalaStewardTimeoutMinutes` | `Int` | `45` | `timeout-minutes` for the scala-steward job |
|
|
84
|
+
| `ciScalaStewardPermissions` | `Map[String, String]` | `contents: read` | Permissions block for `scala-steward.yml`; the action authenticates via the GitHub App's installation token, not `GITHUB_TOKEN`, so no write scope is needed by default |
|
|
85
|
+
| `ciScalaStewardWorkflowEnv` | `Map[String, String]` | `Map.empty` | Extra env vars for the scala-steward job |
|
|
86
|
+
| `ciScalaStewardConfig` | `ScalaStewardConfig` | `ScalaStewardConfig()` | Settings scaffolded into `.scala-steward.conf` on first non-empty render |
|
|
87
|
+
| `ciEnableDependabot` | `Boolean` | `true` | Generates `.github/dependabot.yml`. Overwrites a hand-written one when on; when off, only deletes a copy it generated itself |
|
|
88
|
+
| `ciEnableRegenerateWorkflows` | `Boolean` | `true` | Generates `regenerate-workflows.yml`, which re-runs `ciGenerateGithubWorkflow` on bot PRs and pushes the result to the PR branch. When off, only deletes a copy it generated itself |
|
|
89
|
+
| `ciDependabotConfig` | `DependabotConfig` | one weekly `github-actions` update at `/` | Content of the generated `dependabot.yml` |
|
|
90
|
+
|
|
91
|
+
### Test Matrix
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
| Setting | Type | Default | Description |
|
|
95
|
+
| --- | --- | --- | --- |
|
|
96
|
+
| `ciTargetJavaVersions` | `Seq[String]` | `Seq("17", "21", "25")` | Java versions in the test matrix |
|
|
97
|
+
| `ciDefaultJavaVersion` | `String` | `"17"` | Java version for the non-matrix jobs |
|
|
98
|
+
| `ciTargetScalaVersions` | `Map[String, Seq[String]]` | `Map.empty` | Module to Scala versions. Empty runs a plain `sbt +test` |
|
|
99
|
+
| `ciTargetMinJavaVersions` | `Map[String, String]` | `Map.empty` | Module to minimum Java version, gating modules per matrix entry |
|
|
100
|
+
| `ciGroupSimilarTests` | `Boolean` | `false` | Groups by Java and Scala version instead of one entry per module |
|
|
101
|
+
| `ciMatrixMaxParallel` | `Option[Int]` | `None` | `strategy.max-parallel` |
|
|
102
|
+
|
|
103
|
+
### Jobs and Steps
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
| Setting | Type | Default | Description |
|
|
107
|
+
| --- | --- | --- | --- |
|
|
108
|
+
| `ciBuildJobs` | `Seq[Job]` | one `build` job | Replaces or extends the build jobs |
|
|
109
|
+
| `ciLintJobs` | `Seq[Job]` | one `lint` job | |
|
|
110
|
+
| `ciTestJobs` | `Seq[Job]` | one `test` job | |
|
|
111
|
+
| `ciUpdateReadmeJobs` | `Seq[Job]` | one `update-readme` job | Set to `Seq.empty` if the README is maintained by hand |
|
|
112
|
+
| `ciReportSuccessfulJobs` | `Seq[Job]` | the aggregate `ci` job | Set to `Seq.empty` for a workflow made up entirely of custom jobs that does not want one |
|
|
113
|
+
| `ciReleaseJobs` | `Seq[Job]` | one `release` job | |
|
|
114
|
+
| `ciPostReleaseJobs` | `Seq[Job]` | `release-docs`, `notify-docs-release` | |
|
|
115
|
+
| `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 |
|
|
116
|
+
| `ciReleaseApprovalJobs` | `Seq[String]` | `Seq("ci")` | Job ids the release waits on |
|
|
117
|
+
| `ciCheckArtifactsCompilationSteps` | `Seq[Step]` | `sbt +Test/compile` | |
|
|
118
|
+
| `ciCheckArtifactsBuildSteps` | `Seq[Step]` | `sbt +publishLocal` | |
|
|
119
|
+
| `ciCheckWebsiteBuildProcess` | `Seq[Step]` | `sbt docs/clean; sbt docs/buildWebsite`, then `sbt docs/checkDocsOnFreshWebsite` | Set to `Seq.empty` in a build with no `docs` project |
|
|
120
|
+
| `ciCheckGithubWorkflowSteps` | `Seq[Step]` | `sbt ciCheckGithubWorkflow` | |
|
|
121
|
+
|
|
122
|
+
### Release and Docs
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
| Setting | Type | Default | Description |
|
|
126
|
+
| --- | --- | --- | --- |
|
|
127
|
+
| `ciPublishSnapshots` | `Boolean` | `true` | Also publish SNAPSHOTs on pushes to the default branch |
|
|
128
|
+
| `ciUpdateReadmeCondition` | `Option[Condition]` | `None` | When to run the README job. Defaults to published releases |
|
|
129
|
+
| `ciDocsVersioningScheme` | `DocsVersioning` | `SemanticVersioning` | `SemanticVersioning` or `HashVersioning` |
|
|
130
|
+
| `ciDependencyUpdateBots` | `Seq[DependencyBot]` | Dependabot, Renovate, `ScalaSteward("zio-scala-steward")` | Bots whose PRs are auto-approved and auto-merged |
|
|
131
|
+
|
|
132
|
+
### Tasks
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
| Task | Description |
|
|
136
|
+
| --- | --- |
|
|
137
|
+
| `ciGenerateGithubWorkflow` | Writes `ci.yml`, `auto-approve.yml` and `auto-merge.yml`, plus `deploy-preview.yml` when `ciEnableDeployPreview` is `true` and `release-drafter.yml` (and scaffolds `.github/release-drafter.yml` once) when `ciEnableReleaseDrafter` is `true`, and scala-steward.yml (and scaffolds .scala-steward.conf once, when ciScalaStewardConfig renders non-empty content) when ciEnableScalaSteward is true, `.github/dependabot.yml` when `ciEnableDependabot` is `true`, and `regenerate-workflows.yml` when `ciEnableRegenerateWorkflows` is `true` |
|
|
138
|
+
| `ciCheckGithubWorkflow` | Regenerates and fails if the committed files are stale |
|
|
139
|
+
| `ciGenerateAutoApproveWorkflow` | Writes `auto-approve.yml` only |
|
|
140
|
+
| `ciGenerateAutoMergeWorkflow` | Writes `auto-merge.yml` only |
|
|
141
|
+
|
|
142
|
+
## Types Used in Settings
|
|
143
|
+
|
|
144
|
+
The types that the settings above take, such as `Job`, `Step`, `Concurrency`, `DependencyBot` and `DeployPreviewMode`, are described in [ZIO SBT GitHub Actions](./githubactions.md). They live in `zio.sbt.githubactions` and are not exported through `autoImport`, so import them explicitly. The reusable steps live in `zio.sbt.ZioSbtCiPlugin`.
|
|
145
|
+
|
|
146
|
+
## Helper Methods
|
|
147
|
+
|
|
148
|
+
`targetScalaVersionsFor(projects*)` takes a list of projects and returns a `Map` from each project id to its `crossScalaVersions`. It is meant for `ciTargetScalaVersions`, as shown in [Test Against Several Scala and Java Versions](../how-to-guides/test-against-several-scala-and-java-versions.md).
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ecosystem
|
|
3
|
+
title: "ZIO SBT Ecosystem"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`ZioSbtEcosystemPlugin` provides the settings, tasks and commands that are common to every ZIO project. It is an auto plugin with `trigger = allRequirements`, so having it on the classpath enables it. It requires the sbt-header, sbt-scalafix, sbt-scalafmt and sbt-buildinfo plugins, which come with it.
|
|
7
|
+
|
|
8
|
+
To install it, add `addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.11")` to `project/plugins.sbt`, as described in [Installation](../index.md#installation).
|
|
9
|
+
|
|
10
|
+
## Settings
|
|
11
|
+
|
|
12
|
+
The plugin defines these keys. The first seven are set at the `ThisBuild` level. `welcomeBannerEnabled` and `usefulTasksAndSettings` are set in each project.
|
|
13
|
+
|
|
14
|
+
| Setting | Type | Default | Description |
|
|
15
|
+
| ------------------------ | --------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
16
|
+
| `scala212` | `String` | `"2.12.21"` | The Scala 2.12 version of the build |
|
|
17
|
+
| `scala213` | `String` | `"2.13.18"` | The Scala 2.13 version of the build |
|
|
18
|
+
| `scala3` | `String` | `"3.9.0"` | The Scala 3 version of the build |
|
|
19
|
+
| `scalaVersion` | `String` | `scala213.value` | Set by the plugin, so a build compiles with Scala 2.13 unless it overrides this |
|
|
20
|
+
| `crossScalaVersions` | `Seq[String]` | `Seq(scala212, scala213, scala3)` | Set by the plugin |
|
|
21
|
+
| `zioVersion` | `String` | `"2.1.22"` | The ZIO version that `enableZIO` adds as a dependency |
|
|
22
|
+
| `javaPlatform` | `String` | `"17"` | The Java version passed to `-source` and `-target` and used for Scala compiler options |
|
|
23
|
+
| `welcomeBannerEnabled` | `Boolean` | `true` | Whether sbt prints the welcome banner with the list of useful commands on startup |
|
|
24
|
+
| `usefulTasksAndSettings` | `Map[String, String]` | the `lint`, `fmt`, `fix`, `prepare`, `quiet` and `publish-all` commands and the strict-compile tasks | Name and description pairs that the welcome banner prints |
|
|
25
|
+
|
|
26
|
+
The defaults of `scala212`, `scala213`, `scala3` and `zioVersion` are baked into the version of the plugin, so upgrading the plugin changes them. Set `zioVersion` explicitly in every build:
|
|
27
|
+
|
|
28
|
+
```scala
|
|
29
|
+
ThisBuild / zioVersion := "2.1.22"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
:::note
|
|
33
|
+
Don't rely on `zioVersion`'s default. It's baked into whichever version of zio-sbt-ecosystem you depend on, so upgrading the plugin—including via an automated dependency-update PR—can silently change your project's own ZIO version along with it. Setting `zioVersion` explicitly keeps that a deliberate decision you make, not a side effect of a plugin bump. Every ZIO ecosystem project (zio-logging, zio-kafka, zio-cache, and others) already follows this practice.
|
|
34
|
+
:::
|
|
35
|
+
|
|
36
|
+
The Scala version settings are plain `String` keys, so they can define `crossScalaVersions` or any other setting:
|
|
37
|
+
|
|
38
|
+
```scala
|
|
39
|
+
crossScalaVersions := Seq(scala212.value, scala213.value, scala3.value)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The plugin also sets these build-wide defaults: `organization := "dev.zio"`, the Apache 2 `licenses`, `homepage` and `scmInfo` derived from the lower-cased project name (`https://zio.dev/<name>` and `https://github.com/zio/<name>`), the `pgp*` keys for signing, and `onChangedBuildSource := ReloadOnSourceChanges`.
|
|
43
|
+
|
|
44
|
+
## Commands
|
|
45
|
+
|
|
46
|
+
The plugin registers these sbt commands. Each one except `quiet off` first turns the welcome banner off.
|
|
47
|
+
|
|
48
|
+
| Command | What it runs |
|
|
49
|
+
| ------------- | ----------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| `fmt` | `scalafmtSbt`, then `+scalafmt` and `+Test / scalafmt`: formats the sources |
|
|
51
|
+
| `lint` | `enableStrictCompile`, the cross-built scalafmt checks, `scalafix --check`, then `disableStrictCompile` |
|
|
52
|
+
| `fix` | `Compile / scalafix` and `Test / scalafix`: applies the scalafix rules |
|
|
53
|
+
| `prepare` | The scalafmt formatting tasks, then `fix`: prepares the sources for a pull request |
|
|
54
|
+
| `publish-all` | `project /` then `+publishSigned`: signs and publishes all artifacts |
|
|
55
|
+
| `quiet` | `quiet on` mutes the welcome banner and `quiet off` shows it again |
|
|
56
|
+
|
|
57
|
+
`addCommand(commands, name, description)` adds a command of your own that the welcome banner lists:
|
|
58
|
+
|
|
59
|
+
```scala
|
|
60
|
+
addCommand(List("scalafmtAll", "Test / compile"), "check-all", "Formats and compiles everything")
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Tasks
|
|
64
|
+
|
|
65
|
+
The plugin defines three tasks in `zio.sbt.Tasks`.
|
|
66
|
+
|
|
67
|
+
| Task | Description |
|
|
68
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
69
|
+
| `enableStrictCompile` | Sets the system property `enable.strict.compilation` to `true` |
|
|
70
|
+
| `disableStrictCompile` | Sets the system property `enable.strict.compilation` to `false` |
|
|
71
|
+
| `build` | Runs `clean`, `enableStrictCompile`, `Compile / compile`, `Test / compile` and `Test / test`, then `disableStrictCompile` |
|
|
72
|
+
|
|
73
|
+
The plugin's own settings do not read the `enable.strict.compilation` property. `stdSettings` adds `-Xfatal-warnings` on Scala 2 when the `CI` environment variable is set, whatever the property says. A build that wants warnings as errors only under `lint` can read the property in its own `scalacOptions`.
|
|
74
|
+
|
|
75
|
+
## Standard Settings
|
|
76
|
+
|
|
77
|
+
`stdSettings` is the entry point for configuring a project. Its parameters are:
|
|
78
|
+
|
|
79
|
+
| Parameter | Type | Default | Description |
|
|
80
|
+
| ------------------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------------- |
|
|
81
|
+
| `name` | `Option[String]` | `None` | Sets the sbt `name` when present |
|
|
82
|
+
| `packageName` | `Option[String]` | `None` | Enables `buildInfoSettings` with this package for sbt-buildinfo when present |
|
|
83
|
+
| `javaPlatform` | `String` | `"17"` | Sets the `javaPlatform` setting and the `-source` and `-target` javac options |
|
|
84
|
+
| `enableKindProjector` | `Boolean` | `true` | Adds the kind-projector compiler plugin on Scala 2 |
|
|
85
|
+
| `enableCrossProject` | `Boolean` | `false` | Adds `crossProjectSettings` |
|
|
86
|
+
| `enableScalafix` | `Boolean` | `true` | Adds `scalafixSettings` |
|
|
87
|
+
| `turnCompilerWarningIntoErrors` | `Boolean` | `true` | Adds `-Xfatal-warnings` on Scala 2 when the `CI` environment variable is set |
|
|
88
|
+
|
|
89
|
+
Besides these, `stdSettings` adds the standard `scalacOptions` for the Scala version, runs `Test / parallelExecution` on Scala 2 only, enables `autoAPIMappings` and adds the better-monadic-for compiler plugin.
|
|
90
|
+
|
|
91
|
+
`stdSettings` takes the project name and, optionally, the package name for build info:
|
|
92
|
+
|
|
93
|
+
```scala
|
|
94
|
+
lazy val core = project
|
|
95
|
+
.settings(stdSettings(name = Some("my-library"), packageName = Some("com.example.mylibrary")))
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Dependency and Platform Settings
|
|
99
|
+
|
|
100
|
+
These methods return sbt settings that a project adds with `.settings(...)`.
|
|
101
|
+
|
|
102
|
+
| Method | Description |
|
|
103
|
+
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| `enableZIO(enableStreaming = false, enableTesting = true)` | Adds `zio` with `zioVersion`, plus `zio-streams` and the ZIO Test framework as requested |
|
|
105
|
+
| `jsSettings` | Settings for Scala.js projects: forks `Test` only on the JVM platform |
|
|
106
|
+
| `nativeSettings` | Settings for Scala Native projects: skips `doc` and replaces `Test / test` with a compile of the tests, and forks `Test` only on the JVM platform |
|
|
107
|
+
| `scalajs` | Adds the `-scalajs` option on Scala 3 |
|
|
108
|
+
| `scalafixSettings` | Enables semanticdb (except on Scala 3) and adds the scaluzzi scalafix rules |
|
|
109
|
+
| `scalaReflectTestSettings` | Adds `scala-reflect` in the `Test` configuration, from the Scala 2.13 version on Scala 3 |
|
|
110
|
+
| `crossProjectSettings` | Adds the platform- and Scala-version-specific source directories (for example `scala-2.13+`, `scala-3.x`) to `Compile` and `Test` |
|
|
111
|
+
| `buildInfoSettings(packageName)` | Exposes `name`, `version`, `scalaVersion`, `sbtVersion` and `isSnapshot` in sbt-buildinfo |
|
|
112
|
+
| `macroExpansionSettings` | Enables macro annotations on Scala 2.13 and the macro paradise plugin on 2.12 |
|
|
113
|
+
| `macroDefinitionSettings` | Adds `-language:experimental.macros` and the provided `scala-reflect` and `scala-compiler` on Scala 2 |
|
|
114
|
+
|
|
115
|
+
`enableZIO` adds ZIO using `zioVersion`:
|
|
116
|
+
|
|
117
|
+
```scala
|
|
118
|
+
lazy val core = project
|
|
119
|
+
.settings(enableZIO(enableStreaming = true))
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Version-Specific Helpers
|
|
123
|
+
|
|
124
|
+
Each helper takes the Scala binary versions it applies to, such as `"2.13"` or `"3"`, then the options or dependencies. The `optionsOn*` and `dependenciesOn*` methods return initializations and the `add*` methods return settings.
|
|
125
|
+
|
|
126
|
+
| Method | Description |
|
|
127
|
+
| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
128
|
+
| `optionsOn(versions*)(options*)` | The options when the Scala binary version is one of `versions`, an empty `Seq` otherwise |
|
|
129
|
+
| `optionsOnExcept(versions*)(options*)` | The options when the Scala binary version is none of `versions` |
|
|
130
|
+
| `optionsOnOrElse(versions*)(options*)(other*)` | The options on the listed versions and the other options everywhere else |
|
|
131
|
+
| `addOptionsOn`, `addOptionsOnExcept`, `addOptionsOnOrElse` | The same three, as a setting that appends to `scalacOptions` |
|
|
132
|
+
| `dependenciesOn(versions*)(modules*)` | The modules when the Scala binary version is one of `versions` |
|
|
133
|
+
| `dependenciesOnExcept(versions*)(modules*)` | The modules when the Scala binary version is none of `versions` |
|
|
134
|
+
| `dependenciesOnOrElse(versions*)(modules*)(other*)` | The modules on the listed versions and the other modules everywhere else |
|
|
135
|
+
| `addDependenciesOn`, `addDependenciesOnExcept`, `addDependenciesOnOrElse` | The same three, as a setting that appends to `libraryDependencies` |
|
|
136
|
+
|
|
137
|
+
`addOptionsOn` adds compiler options for the listed Scala binary versions only:
|
|
138
|
+
|
|
139
|
+
```scala
|
|
140
|
+
addOptionsOn("2.13")("-Ymacro-annotations")
|
|
141
|
+
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: githubactions
|
|
3
|
+
title: "ZIO SBT GitHub Actions"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`zio-sbt-githubactions` is a Scala model of GitHub Actions workflows and of the config files of dependency bots. [ZIO SBT CI](./ci.md) uses it to render the generated YAML, and a build uses it to describe jobs, steps and triggers in `build.sbt`. The module is published as a dependency of `zio-sbt-ci`, so it needs no installation of its own. Its types live in the `zio.sbt.githubactions` package and are not exported through `autoImport`, so import them explicitly.
|
|
7
|
+
|
|
8
|
+
## Workflow Model
|
|
9
|
+
|
|
10
|
+
A `Workflow` holds a name, environment variables, triggers, jobs and an optional `Concurrency`. A `Job` holds steps and the settings of one GitHub Actions job. The following types make up the model.
|
|
11
|
+
|
|
12
|
+
| Type | Description |
|
|
13
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| `Workflow` | Name, `env`, `triggers`, `jobs`, `concurrency` and `permissions`. `withoutPermissions` omits the `permissions` block, which is not the same as an empty map |
|
|
15
|
+
| `Job` | `id`, `name`, `runsOn`, `continueOnError`, `strategy`, `steps`, `need`, `services`, `condition`, `jobTimeout`, `concurrency` and `permissions` |
|
|
16
|
+
| `Strategy` | `Strategy(matrix, maxParallel = None, failFast = true)`, the matrix of a job |
|
|
17
|
+
| `Step` | `Step.SingleStep` has `name`, `id`, `uses`, `condition`, `parameters`, `run` and `env`. `Step.StepSequence` groups several steps |
|
|
18
|
+
| `ActionRef` | The `uses` reference of a step, such as `actions/checkout@v7.0.1` |
|
|
19
|
+
| `Trigger` | `WorkflowDispatch`, `Schedule`, `Release`, `PullRequest`, `PullRequestTarget`, `Push`, `Create`, `WorkflowRun` and `IssueComment` |
|
|
20
|
+
| `Branch` | `Branch.All` or `Branch.Named(name)`, used by push and pull request triggers |
|
|
21
|
+
| `Condition` | `Condition.Expression(expression)` renders as `${{ expression }}`. `Condition.Function(expression)` renders as written. Both combine with `&&` and `\|\|`, but a `Function` cannot be combined |
|
|
22
|
+
| `Service` | A service container: `name`, `image`, `env`, `ports` and `options` |
|
|
23
|
+
| `ImageRef` | The image of a service, such as `ImageRef("postgres:16")` |
|
|
24
|
+
| `ServicePort` | `ServicePort(inner, outer)` renders as `inner:outer` |
|
|
25
|
+
| `Concurrency` | `Concurrency(group, cancelInProgress = CancelInProgress.Always)` |
|
|
26
|
+
| `CancelInProgress` | `Always`, `Never` or `When(condition)` |
|
|
27
|
+
| `OS` | The runner operating system. `OS.UbuntuLatest` renders as `ubuntu-latest` |
|
|
28
|
+
|
|
29
|
+
To change a job that a setting produced, copy it with the `Job` methods `withStrategy`, `withRunsOn`, `withSteps`, `withServices`, `withTimeout` and `withPermissions`. A job's `timeoutMinutes` field is deprecated in favor of `jobTimeout`.
|
|
30
|
+
|
|
31
|
+
The `zio.sbt.V` object resolves the pinned version of an action, so `V("actions/checkout")` returns the `actions/checkout@<version>` reference that the generated workflows use.
|
|
32
|
+
|
|
33
|
+
## CI Setting Types
|
|
34
|
+
|
|
35
|
+
These types are the values of the `ci*` settings of [ZIO SBT CI](./ci.md).
|
|
36
|
+
|
|
37
|
+
| Type | Used by | Description |
|
|
38
|
+
| ------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
|
|
39
|
+
| `DependencyBot` | `ciDependencyUpdateBots` | `Dependabot` (`dependabot[bot]`), `Renovate` (`renovate[bot]`), `ScalaSteward(githubAppName)` (`<githubAppName>[bot]`) and `Custom(login)` |
|
|
40
|
+
| `DeployPreviewMode` | `ciDeployPreviewMode` | `Automatic` or `OnDemand` |
|
|
41
|
+
| `DependabotConfig` | `ciDependabotConfig` | `DependabotConfig(updates)`, by default one weekly `github-actions` update |
|
|
42
|
+
| `DependabotUpdate` | `DependabotConfig` | `ecosystem`, `directory = "/"`, `interval = "weekly"`, `openPullRequestsLimit` and `groups` |
|
|
43
|
+
| `DependabotGroup` | `DependabotUpdate` | `name`, `patterns` and `updateTypes` |
|
|
44
|
+
| `ScalaStewardConfig` | `ciScalaStewardConfig` | The `.scala-steward.conf` content: `pins`, `allow`, `ignore`, `updatesLimit`, `updatePullRequests`, `commitMessage`, `pullRequestsFrequency`, `grouping`, `assignees` and `reviewers` |
|
|
45
|
+
| `ScalaStewardDependency` | `ScalaStewardConfig` | `groupId`, `artifactId` and `version` |
|
|
46
|
+
| `ScalaStewardGroupingRule` | `ScalaStewardConfig` | `name` and a `filter` of `ScalaStewardGroupFilter(group, version)` |
|
|
47
|
+
| `ReleaseDrafterCategory` | `ciReleaseDrafterCategories` | `title` and the `labels` that put a pull request in the category |
|
|
48
|
+
| `ReleaseDrafterVersionResolver`| `ciReleaseDrafterVersionResolver` | The labels for `major`, `minor` and `patch`, and the `default` bump |
|
|
49
|
+
| `ReleaseDrafterAutolabelerRule`| `ciReleaseDrafterAutolabeler` | A `label` and the `files`, `branch`, `title` and `body` patterns that apply it |
|
|
50
|
+
|
|
51
|
+
The how-to guides show these types at work. See [Auto-Approve and Auto-Merge Dependency Update PRs](../how-to-guides/auto-approve-and-auto-merge-dependency-update-prs.md), [Configure Dependabot Updates](../how-to-guides/configure-dependabot-updates.md) and [Customize the Generated CI Jobs](../how-to-guides/customize-the-generated-ci-jobs.md).
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: index
|
|
3
|
+
title: "Reference"
|
|
4
|
+
sidebar_label: "Reference"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
The reference has one page for each module of ZIO SBT. Each page lists the settings, tasks, commands and types of the module, with their types and defaults. For step-by-step instructions, use the How-to Guides instead.
|
|
8
|
+
|
|
9
|
+
| Page | Module | What it covers |
|
|
10
|
+
| --------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------- |
|
|
11
|
+
| [ZIO SBT Ecosystem](./ecosystem.md) | `zio-sbt-ecosystem` | Scala and ZIO version settings, standard settings, the `fmt`, `lint` and `prepare` commands |
|
|
12
|
+
| [ZIO SBT Website](./website.md) | `zio-sbt-website` | Documentation tasks, website settings, README settings and npm publishing |
|
|
13
|
+
| [ZIO SBT CI](./ci.md) | `zio-sbt-ci` | The generated workflows and every `ci*` setting and task |
|
|
14
|
+
| [ZIO SBT GitHub Actions](./githubactions.md) | `zio-sbt-githubactions` | The model of workflows, jobs, steps and bot configuration |
|
|
15
|
+
| [ZIO SBT Source](./source.md) | `zio-sbt-source` | `ExprEval`, `SourceFile` and the `mdoc:embed` modifier |
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: source
|
|
3
|
+
title: "ZIO SBT Source"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
ZIO SBT Source is a Scala 2.13 and Scala 3 cross-compiled library, not an sbt plugin, that provides utilities for self-documenting example code. It contains the `ExprEval` macro, which captures the source text of expressions at compile time and prints it alongside the evaluated result at runtime, `SourceFile` and `SourceReader`, which read source files, and `EmbedSourceModifier`, an mdoc modifier that embeds a source file into a documentation page.
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
|
|
10
|
+
Add the following line to your `libraryDependencies` in the `build.sbt` of the docs project:
|
|
11
|
+
|
|
12
|
+
```scala
|
|
13
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.8.11"
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## ExprEval
|
|
17
|
+
|
|
18
|
+
`ExprEval.show` prints each expression followed by its value:
|
|
19
|
+
|
|
20
|
+
```scala
|
|
21
|
+
import zio.sbt.ExprEval.show
|
|
22
|
+
|
|
23
|
+
show(
|
|
24
|
+
42 + 8,
|
|
25
|
+
"Hello, " + "World!"
|
|
26
|
+
)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
It prints:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
42 + 8
|
|
33
|
+
// 50
|
|
34
|
+
"Hello, " + "World!"
|
|
35
|
+
// Hello, World!
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Comment Labels
|
|
39
|
+
|
|
40
|
+
Consecutive `//` comment lines immediately above the `show` call are printed as a label above the output:
|
|
41
|
+
|
|
42
|
+
```scala
|
|
43
|
+
// Calculate the answer to life, the universe, and everything
|
|
44
|
+
show(6 * 7)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
It prints:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
// Calculate the answer to life, the universe, and everything
|
|
51
|
+
6 * 7
|
|
52
|
+
// 42
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Block Form
|
|
56
|
+
|
|
57
|
+
`show` also accepts a block, with one expression per line:
|
|
58
|
+
|
|
59
|
+
```scala
|
|
60
|
+
show {
|
|
61
|
+
1 + 2
|
|
62
|
+
3 * 4
|
|
63
|
+
"hello"
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Implementation
|
|
68
|
+
|
|
69
|
+
The Scala 3 version is an `inline def` that uses `scala.quoted` to capture the source. The Scala 2.13 version is a whitebox macro that achieves the same. At runtime, `SourceReader` reads the comment lines above the call from the source file, and returns nothing when the file does not exist.
|
|
70
|
+
|
|
71
|
+
## SourceFile
|
|
72
|
+
|
|
73
|
+
`SourceFile` reads a source file and prints it as a fenced code block:
|
|
74
|
+
|
|
75
|
+
| Method | Description |
|
|
76
|
+
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `SourceFile.readSource(path)` | Returns the file content. When `path` does not exist relative to the working directory, it is tried again relative to the parent directory |
|
|
78
|
+
| `SourceFile.fileExtension(path)` | Returns the extension of the file name, used as the language of the fence |
|
|
79
|
+
| `SourceFile.printSource(path, comment = true, showLineNumbers = false)` | Prints a code fence whose language is the file extension. With `comment` the fence has `title="<path>"`, and with `showLineNumbers` it has the `showLineNumbers` flag |
|
|
80
|
+
|
|
81
|
+
`SourceFile.printSource` prints a source file from an mdoc block:
|
|
82
|
+
|
|
83
|
+
```scala
|
|
84
|
+
import zio.sbt.SourceFile
|
|
85
|
+
|
|
86
|
+
SourceFile.printSource("path/to/Example.scala")
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## EmbedSourceModifier
|
|
90
|
+
|
|
91
|
+
`EmbedSourceModifier` extends mdoc with the `embed` modifier. A code fence whose info string is `mdoc:embed:<path>` is replaced by the file at `<path>`, rendered with `SourceFile.printSource`. Leave the body of the fence empty:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
\`\`\`scala mdoc:embed:path/to/Example.scala
|
|
95
|
+
\`\`\`
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
An empty path, or a file that cannot be read, is reported as an mdoc error.
|
|
99
|
+
|
|
100
|
+
### Line Numbers
|
|
101
|
+
|
|
102
|
+
The `:showLineNumbers` flag, or its kebab-case alias `:show-line-numbers`, enables line numbers in [Docusaurus](https://docusaurus.io) code blocks:
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
\`\`\`scala mdoc:embed:path/to/Example.scala:showLineNumbers
|
|
106
|
+
\`\`\`
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Both forms emit `showLineNumbers` in the code fence header.
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: website
|
|
3
|
+
title: "ZIO SBT Website"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`WebsitePlugin` compiles the documentation in the `docs` directory with mdoc, scaffolds, builds and previews a Docusaurus website, publishes the docs to npm and generates the `README.md` of the project. `UnifiedScaladocPlugin` is a small companion that publishes one Scaladoc for several modules.
|
|
7
|
+
|
|
8
|
+
To install the plugin, add `addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.11")` to `project/plugins.sbt` and enable it on the docs project with `enablePlugins(WebsitePlugin)`, as described in [Installation](../index.md#installation).
|
|
9
|
+
|
|
10
|
+
## Tasks
|
|
11
|
+
|
|
12
|
+
The plugin defines these tasks. Run them on the docs project, for example `sbt docs/compileDocs`.
|
|
13
|
+
|
|
14
|
+
| Task | Type | Description |
|
|
15
|
+
| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
16
|
+
| `compileDocs` | `InputKey` | Compiles the documentation inside `docs` with mdoc into `website/docs`. With `--watch` it recompiles on every change |
|
|
17
|
+
| `installWebsite` | `TaskKey` | Creates the website for the project inside `website` with `@zio.dev/create-zio-website`, pinned by `createZioWebsiteVersion`, then runs `npm install`. It does nothing when `website/package.json` exists |
|
|
18
|
+
| `buildWebsite` | `TaskKey` | Runs `installWebsite` and `compileDocs`, installs the npm dependencies if `node_modules` is missing, then builds the site into `website/build` |
|
|
19
|
+
| `previewWebsite` | `TaskKey` | Compiles the docs with `--watch` and runs `npm run start`, which serves the website on `http://localhost:3000` and reloads it when the docs change |
|
|
20
|
+
| `checkDocsOnFreshWebsite` | `TaskKey` | Builds the compiled docs in a freshly scaffolded website, the way the ZIO website builds them. It is skipped when the project has no committed website |
|
|
21
|
+
| `publishToNpm` | `InputKey` | Compiles the docs and publishes `website/docs` to npm under the version given by `docsVersion` |
|
|
22
|
+
| `publishSnapshotToNpm` | `InputKey` | Compiles the docs and publishes them with the project version under the `snapshot` dist-tag, replacing `+` with `--` in the version |
|
|
23
|
+
| `publishHashverToNpm` | `InputKey` | Compiles the docs and publishes them with a hash version, a date plus the short git hash, under the `hash` dist-tag |
|
|
24
|
+
| `generateReadme` | `TaskKey` | Generates `README.md` from `docs/index.md` and the `readme*` settings |
|
|
25
|
+
| `checkReadme` | `TaskKey` | Runs `generateReadme` and fails when `git diff` shows that `README.md` changed |
|
|
26
|
+
|
|
27
|
+
`publishToNpm` puts a prerelease version, such as `1.0.0-beta.1`, under its own dist-tag (`beta`) only when the `latest` tag already points at a stable release. Otherwise the version goes to `latest`, published with an explicit `--tag latest` because npm refuses a prerelease without a tag. The `publishToNpm`, `publishSnapshotToNpm` and `publishHashverToNpm` tasks need `scmInfo` to be set, because they record the repository URL in the package.
|
|
28
|
+
|
|
29
|
+
The `website/docs` directory is generated output, not source. `mdocOut` points there, so `compileDocs`, and anything that runs it, including `generateReadme`, writes compiled documentation into it. To keep it out of version control, add these lines to `.gitignore`:
|
|
30
|
+
|
|
31
|
+
```gitignore
|
|
32
|
+
/website/docs
|
|
33
|
+
/website/build
|
|
34
|
+
/website/node_modules
|
|
35
|
+
/website/.docusaurus
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Committing `website/docs` leaves a `website` directory that holds generated output but no Docusaurus scaffold, and `buildWebsite` then has no `package.json` to install from.
|
|
39
|
+
|
|
40
|
+
## Settings
|
|
41
|
+
|
|
42
|
+
| Setting | Type | Default | Description |
|
|
43
|
+
| ------------------------- | ----------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `websiteDir` | `Path` | `<root>/website` | The website directory |
|
|
45
|
+
| `projectName` | `String` | | The project name, such as `ZIO SBT`, used in the README title and badges. Set it on the docs project |
|
|
46
|
+
| `mainModuleName` | `String` | | The main module, such as `zio-sbt`, used for the artifact in badges. Set it on the docs project |
|
|
47
|
+
| `projectStage` | `ProjectStage` | | The stage badge: `ProductionReady`, `Development`, `Experimental`, `Research`, `Concept` or `Deprecated` |
|
|
48
|
+
| `projectHomePage` | `String` | | Declared by the plugin, but nothing reads it. The README documentation link uses sbt's `homepage` instead |
|
|
49
|
+
| `badgeArtifactId` | `String` | `mainModuleName` plus `_` plus the Scala binary version | The artifact id in the release, snapshot and javadoc badges. Override it for artifacts with other coordinates, such as sbt plugins (`name_2.12_1.0`) |
|
|
50
|
+
| `ciWorkflowName` | `String` | `"CI"` | The name of the CI workflow that the CI badge points at. This is not the key that names the generated workflow; that is `ciWorkflowTitle` of [ZIO SBT CI](./ci.md) |
|
|
51
|
+
| `docsDependencies` | `Seq[ModuleID]` | `Seq.empty` | Dependencies that the docs project adds to `libraryDependencies` |
|
|
52
|
+
| `docsVersioningScheme` | `VersioningScheme` | `VersioningScheme.SemanticVersioning` | `SemanticVersioning` or `HashVersioning` |
|
|
53
|
+
| `docsVersion` | `String` | derived from `docsVersioningScheme` | The version of the docs npm package: the latest release with semantic versioning, a date and short git hash with hash versioning |
|
|
54
|
+
| `createZioWebsiteVersion` | `String` | `"0.1.0"` | The version of the `@zio.dev/create-zio-website` npm package that scaffolds the website |
|
|
55
|
+
| `npmToken` | `String` | | Declared by the plugin, but its tasks do not read it. Publishing uses the credentials of the `npm` command |
|
|
56
|
+
|
|
57
|
+
`projectName` and `mainModuleName` have no default, so the docs project must set them. `projectStage` is set with an object, for example `ProjectStage.ProductionReady`.
|
|
58
|
+
|
|
59
|
+
## mdoc Variables
|
|
60
|
+
|
|
61
|
+
The plugin adds these variables to `mdocVariables`, so a documentation page can write them between `@` signs:
|
|
62
|
+
|
|
63
|
+
| Variable | Value |
|
|
64
|
+
| ------------------ | --------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `0.8.11` | The latest release version, or the project version when there is no release |
|
|
66
|
+
| `0.8.11` | The latest release version, or `NOT RELEASED YET` |
|
|
67
|
+
| `0.8.11` | The current project version |
|
|
68
|
+
| `[](https://github.com/zio/zio/wiki/Project-Stages)  [](https://central.sonatype.com/artifact/dev.zio/zio-sbt-website_2.12_1.0) [](https://central.sonatype.com/repository/maven-snapshots/dev/zio/zio-sbt-website_2.12_1.0/) [](https://javadoc.io/doc/dev.zio/zio-sbt-website_2.12_1.0) [](https://github.com/zio/zio-sbt)` | The stage, CI, snapshot and GitHub star badges, plus the release and javadoc badges once a release exists |
|
|
69
|
+
|
|
70
|
+
The plugin also passes `--markdown-extensions` for `md`, `html` and `mdx` to mdoc, so `docs/index.mdx` is processed like `docs/index.md`.
|
|
71
|
+
|
|
72
|
+
## README Settings
|
|
73
|
+
|
|
74
|
+
`generateReadme` builds `README.md` from the introduction in `docs/index.md` and these settings. Each one is a `String` with Markdown content, except `readmeShowTitle`. An empty string omits the Acknowledgement, Credits and Maintainers sections. The other sections are always written, so an empty string leaves their heading with no content.
|
|
75
|
+
|
|
76
|
+
| Setting | Default | Section it fills |
|
|
77
|
+
| ---------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
78
|
+
| `readmeBanner` | `""` | A banner above the introduction |
|
|
79
|
+
| `readmeShowTitle` | `None` | Whether the README starts with `# <projectName>`. `None` shows the title unless `readmeBanner` is set. The type is `Option[Boolean]` |
|
|
80
|
+
| `readmeDocumentation` | A link to the `homepage` setting of the build | Documentation |
|
|
81
|
+
| `readmeContribution` | A link to the ZIO contributor's guide | Contributing |
|
|
82
|
+
| `readmeCodeOfConduct` | A link to the ZIO code of conduct | Code of Conduct |
|
|
83
|
+
| `readmeSupport` | A Discord chat badge and link | Support |
|
|
84
|
+
| `readmeLicense` | A link to the `LICENSE` file | License |
|
|
85
|
+
| `readmeAcknowledgement`| `""` | Acknowledgement |
|
|
86
|
+
| `readmeCredits` | `""` | Credits |
|
|
87
|
+
| `readmeMaintainers` | `""` | Maintainers |
|
|
88
|
+
|
|
89
|
+
A README setting can be appended to as well as replaced:
|
|
90
|
+
|
|
91
|
+
```scala
|
|
92
|
+
readmeContribution := readmeContribution.value + "\n\nRun `sbt prepare` before you submit a pull request."
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Unified Scaladoc
|
|
96
|
+
|
|
97
|
+
`UnifiedScaladocPlugin` requires the sbt-unidoc `ScalaUnidocPlugin` and has `noTrigger`, so a project enables it explicitly. It sets `Compile / doc` to `ScalaUnidoc / doc`, so `doc` produces one Scaladoc for every module that unidoc includes:
|
|
98
|
+
|
|
99
|
+
```scala
|
|
100
|
+
lazy val docs = project
|
|
101
|
+
.enablePlugins(WebsitePlugin, UnifiedScaladocPlugin)
|
|
102
|
+
.settings(ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(core))
|
|
103
|
+
```
|