@zio.dev/zio-sbt 0.8.9 → 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/sidebars.js
CHANGED
|
@@ -1,11 +1,65 @@
|
|
|
1
1
|
const sidebars = {
|
|
2
2
|
sidebar: [
|
|
3
|
+
{
|
|
4
|
+
type: "doc",
|
|
5
|
+
id: "index",
|
|
6
|
+
label: "Introduction"
|
|
7
|
+
},
|
|
8
|
+
{
|
|
9
|
+
type: "doc",
|
|
10
|
+
id: "getting-started",
|
|
11
|
+
label: "Getting Started"
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
type: "category",
|
|
15
|
+
label: "Concepts",
|
|
16
|
+
collapsed: false,
|
|
17
|
+
link: { type: "doc", id: "concepts/index" },
|
|
18
|
+
items: [
|
|
19
|
+
"concepts/how-the-plugins-fit-together",
|
|
20
|
+
"concepts/generated-files"
|
|
21
|
+
]
|
|
22
|
+
},
|
|
3
23
|
{
|
|
4
24
|
type: "category",
|
|
5
|
-
label: "
|
|
25
|
+
label: "Reference",
|
|
6
26
|
collapsed: false,
|
|
7
|
-
link: { type: "doc", id: "index" },
|
|
8
|
-
items: [
|
|
27
|
+
link: { type: "doc", id: "reference/index" },
|
|
28
|
+
items: [
|
|
29
|
+
"reference/ecosystem",
|
|
30
|
+
"reference/website",
|
|
31
|
+
"reference/ci",
|
|
32
|
+
"reference/githubactions",
|
|
33
|
+
"reference/source"
|
|
34
|
+
]
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
type: "doc",
|
|
38
|
+
id: "tutorials/set-up-a-new-zio-library",
|
|
39
|
+
label: "Tutorial"
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
type: "category",
|
|
43
|
+
label: "How-to Guides",
|
|
44
|
+
collapsed: true,
|
|
45
|
+
items: [
|
|
46
|
+
"how-to-guides/publish-a-releases-docs-again",
|
|
47
|
+
"how-to-guides/auto-approve-and-auto-merge-dependency-update-prs",
|
|
48
|
+
"how-to-guides/regenerate-workflows-on-bot-prs",
|
|
49
|
+
"how-to-guides/enable-netlify-deploy-previews",
|
|
50
|
+
"how-to-guides/draft-releases-with-release-drafter",
|
|
51
|
+
"how-to-guides/configure-dependabot-updates",
|
|
52
|
+
"how-to-guides/configure-scala-steward",
|
|
53
|
+
"how-to-guides/keep-the-workflow-in-sync",
|
|
54
|
+
"how-to-guides/customize-the-generated-ci-jobs",
|
|
55
|
+
"how-to-guides/build-a-workflow-of-only-custom-jobs",
|
|
56
|
+
"how-to-guides/set-job-timeouts",
|
|
57
|
+
"how-to-guides/control-ci-concurrency",
|
|
58
|
+
"how-to-guides/add-a-service-container-to-a-job",
|
|
59
|
+
"how-to-guides/change-the-workflow-environment",
|
|
60
|
+
"how-to-guides/test-against-several-scala-and-java-versions",
|
|
61
|
+
"how-to-guides/customize-the-generated-readme"
|
|
62
|
+
]
|
|
9
63
|
}
|
|
10
64
|
]
|
|
11
65
|
};
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: set-up-a-new-zio-library
|
|
3
|
+
title: "Tutorial: Set Up a New ZIO Library"
|
|
4
|
+
sidebar_label: "Set Up a New ZIO Library"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
In this tutorial, we build the sbt setup of a small library called `zio-greeter` from an empty directory. By the end, the project formats and lints with one command, has a documentation website with a generated README, and has a generated GitHub workflow that tests it.
|
|
8
|
+
|
|
9
|
+
We use all three plugins of ZIO SBT, one per step. The tutorial assumes sbt and Node.js are installed and that the project lives in a Git repository on GitHub.
|
|
10
|
+
|
|
11
|
+
## Step 1: Create the Build
|
|
12
|
+
|
|
13
|
+
Let's start with the files sbt needs. In an empty directory, create `project/build.properties` with a current sbt version, then `project/plugins.sbt`:
|
|
14
|
+
|
|
15
|
+
```scala
|
|
16
|
+
// Standard settings, compiler options and the fmt, lint and prepare commands
|
|
17
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.8.11")
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Next, create `build.sbt`. We set the ZIO version explicitly, so that upgrading the plugin never changes it:
|
|
21
|
+
|
|
22
|
+
```scala
|
|
23
|
+
ThisBuild / zioVersion := "2.1.22"
|
|
24
|
+
|
|
25
|
+
lazy val root = project
|
|
26
|
+
.in(file("."))
|
|
27
|
+
.settings(stdSettings(name = Some("zio-greeter")))
|
|
28
|
+
.settings(enableZIO())
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Run `sbt compile`. The welcome banner lists the commands the plugin added, which means the plugin is active.
|
|
32
|
+
|
|
33
|
+
## Step 2: Write Some Code and Format It
|
|
34
|
+
|
|
35
|
+
Create `src/main/scala/Greeter.scala`:
|
|
36
|
+
|
|
37
|
+
```scala
|
|
38
|
+
object Greeter {
|
|
39
|
+
def greet(name: String): String = s"Hello, $name!"
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
To format the code and apply the scalafix rules, run:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
sbt prepare
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
To check that nothing is left to fix, the way CI will, run `sbt lint`. It passes when `prepare` left nothing to change.
|
|
50
|
+
|
|
51
|
+
## Step 3: Add the Documentation
|
|
52
|
+
|
|
53
|
+
Now we add the website plugin. Append it to `project/plugins.sbt`:
|
|
54
|
+
|
|
55
|
+
```scala
|
|
56
|
+
// Builds, previews and publishes the documentation website
|
|
57
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.8.11")
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
In `build.sbt`, add a `docs` project that depends on the library:
|
|
61
|
+
|
|
62
|
+
```scala
|
|
63
|
+
lazy val docs = project
|
|
64
|
+
.in(file("zio-greeter-docs"))
|
|
65
|
+
.settings(
|
|
66
|
+
moduleName := "zio-greeter-docs",
|
|
67
|
+
projectName := "ZIO Greeter",
|
|
68
|
+
mainModuleName := (root / moduleName).value,
|
|
69
|
+
projectStage := ProjectStage.Development
|
|
70
|
+
)
|
|
71
|
+
.dependsOn(root)
|
|
72
|
+
.enablePlugins(WebsitePlugin)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Create `docs/index.md`:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
---
|
|
79
|
+
id: index
|
|
80
|
+
title: "Introduction to ZIO Greeter"
|
|
81
|
+
sidebar_label: "Introduction"
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
ZIO Greeter greets people.
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Writing `[](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)` on its own line of the introduction adds the stage, CI, snapshot and GitHub star badges to the page and to the README. The release and javadoc badges appear once the project has a release.
|
|
88
|
+
|
|
89
|
+
Compile the docs and create the website:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
sbt docs/compileDocs
|
|
93
|
+
sbt docs/installWebsite
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Add the generated directories to `.gitignore`:
|
|
97
|
+
|
|
98
|
+
```gitignore
|
|
99
|
+
/website/docs
|
|
100
|
+
/website/build
|
|
101
|
+
/website/node_modules
|
|
102
|
+
/website/.docusaurus
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
To preview the website, run `sbt docs/previewWebsite` and open `http://localhost:3000`.
|
|
106
|
+
|
|
107
|
+
## Step 4: Generate the README
|
|
108
|
+
|
|
109
|
+
The README comes from `docs/index.md`, so the two never drift apart. Generate it, then check that it is up to date:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
sbt docs/generateReadme
|
|
113
|
+
sbt docs/checkReadme
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Step 5: Generate the CI Workflow
|
|
117
|
+
|
|
118
|
+
Finally, we add the CI plugin. Append it to `project/plugins.sbt`:
|
|
119
|
+
|
|
120
|
+
```scala
|
|
121
|
+
// Generates the GitHub Actions workflows from build.sbt
|
|
122
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.8.11")
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Tell the workflow which Scala versions to test:
|
|
126
|
+
|
|
127
|
+
```scala
|
|
128
|
+
ThisBuild / ciTargetScalaVersions := targetScalaVersionsFor(root).value
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Then generate the workflow files:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
sbt ciGenerateGithubWorkflow
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The `.github` directory now holds `ci.yml` and the other generated workflows. Commit them together with the rest of the project. From now on a pull request runs the `build`, `lint` and `test` jobs, and `sbt ciCheckGithubWorkflow` tells us when the committed files fall behind `build.sbt`.
|
|
138
|
+
|
|
139
|
+
## What We Built
|
|
140
|
+
|
|
141
|
+
We set up one project with the ecosystem plugin for formatting and linting, the website plugin for documentation and the README, and the CI plugin for the workflow. To go further, see the How-to Guides, for example [Enable Netlify Deploy Previews](../how-to-guides/enable-netlify-deploy-previews.md) and [Publish a Release's Docs Again](../how-to-guides/publish-a-releases-docs-again.md).
|