@zio.dev/zio-sbt 0.5.3 → 0.6.3
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/index.md +67 -75
- 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.
|
|
16
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.
|
|
17
|
-
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.
|
|
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")
|
|
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.
|
|
104
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.6.3")
|
|
105
105
|
|
|
106
106
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
107
107
|
```
|
|
@@ -129,86 +129,35 @@ This will generate a GitHub workflow file inside the `.github/workflows` directo
|
|
|
129
129
|
>
|
|
130
130
|
> To use this plugin, we also need to install [ZIO Assistant](https://github.com/apps/zio-assistant) bot.
|
|
131
131
|
|
|
132
|
-
|
|
132
|
+
### Auto-Approving and Auto-Merging Dependency Update PRs
|
|
133
133
|
|
|
134
|
-
|
|
134
|
+
Besides `ci.yml`, the `ciGenerateGithubWorkflow` task also generates two more workflow files: `auto-approve.yml` and `auto-merge.yml`. These workflows automatically approve and enable GitHub's native auto-merge (squash strategy) on pull requests opened by dependency-update bots, such as [Scala Steward](https://github.com/scala-steward-org/scala-steward), [Dependabot](https://github.com/dependabot), and [Renovate](https://github.com/renovatebot/renovate).
|
|
135
135
|
|
|
136
|
-
|
|
136
|
+
Both workflows trigger on `pull_request_target` and also support `workflow_dispatch`, which backfills the approval/auto-merge on every currently open PR from the configured bots—handy for recovering PRs that were opened before the workflow existed, or after a workflow bug is fixed.
|
|
137
137
|
|
|
138
|
-
|
|
138
|
+
The set of trusted bots is controlled by the `ciDependencyUpdateBots` setting, which takes a `Seq[DependencyBot]`:
|
|
139
139
|
|
|
140
140
|
```scala
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
The plugin is auto-enabled. Configure in `build.sbt`:
|
|
145
|
-
|
|
146
|
-
```scala
|
|
147
|
-
// Required: specify your GitHub repository
|
|
148
|
-
ghRepo := "your-org/your-repo"
|
|
149
|
-
|
|
150
|
-
// Optional: override the default data directory (defaults to .zio-sbt)
|
|
151
|
-
ghDir := file(".zio-sbt")
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
### Commands
|
|
155
|
-
|
|
156
|
-
| Command | Description |
|
|
157
|
-
|---------|-------------|
|
|
158
|
-
| `gh-sync` | Fetch data from GitHub and build/update the search database. On first run (or with `--force`), does a full fetch and rebuild. On subsequent runs, fetches only new/updated items incrementally. |
|
|
159
|
-
| `gh-query <query>` | Full-text search across issues and PRs. Supports `--verbose` flag to include body text. |
|
|
160
|
-
| `gh-status` | Show database statistics (issue/PR/comment counts, last fetch time). |
|
|
161
|
-
|
|
162
|
-
### Usage
|
|
163
|
-
|
|
164
|
-
```bash
|
|
165
|
-
# Fetch all issues/PRs and build the database
|
|
166
|
-
sbt gh-sync
|
|
167
|
-
|
|
168
|
-
# Incrementally fetch new/updated items
|
|
169
|
-
sbt gh-sync
|
|
141
|
+
import zio.sbt.githubactions.DependencyBot
|
|
170
142
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
# Search with full body content
|
|
178
|
-
sbt "gh-query --verbose codec"
|
|
179
|
-
|
|
180
|
-
# Check database statistics
|
|
181
|
-
sbt gh-status
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
### Dependencies
|
|
185
|
-
|
|
186
|
-
The plugin checks for all required dependencies before running any command and reports clear
|
|
187
|
-
error messages with install instructions if anything is missing.
|
|
188
|
-
|
|
189
|
-
| Dependency | Required by | Install |
|
|
190
|
-
|---|---|---|
|
|
191
|
-
| `bash` | `gh-sync` | https://www.gnu.org/software/bash/ |
|
|
192
|
-
| `gh` (GitHub CLI) | `gh-sync` | https://cli.github.com |
|
|
193
|
-
| `jq` | `gh-sync` | https://jqlang.github.io/jq/download/ |
|
|
194
|
-
| `python3` | all commands | https://www.python.org/downloads/ |
|
|
195
|
-
| `sqlite3` with [FTS5](https://www.sqlite.org/fts5.html) | `gh-sync`, `gh-query` | Ensure your Python's sqlite3 is built with FTS5 support |
|
|
196
|
-
|
|
197
|
-
Before running `gh-sync` for the first time, authenticate the GitHub CLI:
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
gh auth login
|
|
143
|
+
ciDependencyUpdateBots := Seq(
|
|
144
|
+
DependencyBot.Dependabot,
|
|
145
|
+
DependencyBot.Renovate,
|
|
146
|
+
DependencyBot.ScalaSteward("zio-scala-steward"),
|
|
147
|
+
DependencyBot.Custom("some-other-bot[bot]")
|
|
148
|
+
)
|
|
201
149
|
```
|
|
202
150
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
151
|
+
- `DependencyBot.Dependabot` — matches login `dependabot[bot]`
|
|
152
|
+
- `DependencyBot.Renovate` — matches login `renovate[bot]`
|
|
153
|
+
- `DependencyBot.ScalaSteward(githubAppName)` — matches login `<githubAppName>[bot]`, where `githubAppName` is the name of the GitHub App you registered for Scala Steward
|
|
154
|
+
- `DependencyBot.Custom(login)` — matches any exact GitHub login, for bots not covered by the predefined cases
|
|
206
155
|
|
|
207
|
-
The
|
|
156
|
+
The default value mirrors the bots used by the `zio/zio` repository: `Seq(DependencyBot.Dependabot, DependencyBot.Renovate, DependencyBot.ScalaSteward("zio-scala-steward"))`. If your Scala Steward GitHub App has a different name, override the setting with the correct `ScalaSteward` app name.
|
|
208
157
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
158
|
+
> **Note:**
|
|
159
|
+
>
|
|
160
|
+
> 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.
|
|
212
161
|
|
|
213
162
|
## ZIO SBT Source
|
|
214
163
|
|
|
@@ -219,7 +168,7 @@ ZIO SBT Source is a Scala 2.13 + Scala 3 cross-compiled library that provides ut
|
|
|
219
168
|
Add the following line to your `libraryDependencies` in `build.sbt`:
|
|
220
169
|
|
|
221
170
|
```scala
|
|
222
|
-
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.
|
|
171
|
+
libraryDependencies += "dev.zio" %% "zio-sbt-source" % "0.6.3"
|
|
223
172
|
```
|
|
224
173
|
|
|
225
174
|
### Features
|
|
@@ -272,6 +221,49 @@ show {
|
|
|
272
221
|
}
|
|
273
222
|
```
|
|
274
223
|
|
|
224
|
+
### SourceFile: Embedding Source Code in Documentation
|
|
225
|
+
|
|
226
|
+
The `SourceFile` utility provides methods for embedding source files into mdoc documentation with support for syntax highlighting and line numbers:
|
|
227
|
+
|
|
228
|
+
```scala
|
|
229
|
+
import zio.sbt.SourceFile
|
|
230
|
+
|
|
231
|
+
// Embed a source file in mdoc
|
|
232
|
+
SourceFile.printSource("path/to/Example.scala")
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
This generates a fenced code block with the file's language tag detected from its extension.
|
|
236
|
+
|
|
237
|
+
### EmbedSourceModifier: mdoc Plugin for Source Embedding
|
|
238
|
+
|
|
239
|
+
The `EmbedSourceModifier` extends mdoc with an `embed` directive for embedding source files directly from markdown.
|
|
240
|
+
Use the modifier name `embed` followed by the file path:
|
|
241
|
+
|
|
242
|
+
```
|
|
243
|
+
\`\`\`scala mdoc:embed:path/to/Example.scala
|
|
244
|
+
\`\`\`
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Renders as a fenced code block with syntax highlighting based on file extension.
|
|
248
|
+
|
|
249
|
+
#### Docusaurus Line Numbers
|
|
250
|
+
|
|
251
|
+
To enable line numbers in [Docusaurus](https://docusaurus.io) code blocks, add the `:showLineNumbers` flag (or kebab-case `:show-line-numbers` alias):
|
|
252
|
+
|
|
253
|
+
```
|
|
254
|
+
\`\`\`scala mdoc:embed:path/to/Example.scala:showLineNumbers
|
|
255
|
+
\`\`\`
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
or
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
\`\`\`scala mdoc:embed:path/to/Example.scala:show-line-numbers
|
|
262
|
+
\`\`\`
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Both forms emit `showLineNumbers` in the code fence header, enabling line numbering in the rendered documentation.
|
|
266
|
+
|
|
275
267
|
### Implementation Details
|
|
276
268
|
|
|
277
269
|
- **Scala 3**: Uses `scala.quoted.*` with `inline def` for compile-time source capture
|