@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.
Files changed (30) hide show
  1. package/concepts/generated-files.md +22 -0
  2. package/concepts/how-the-plugins-fit-together.md +29 -0
  3. package/concepts/index.md +10 -0
  4. package/getting-started.md +91 -0
  5. package/how-to-guides/add-a-service-container-to-a-job.md +28 -0
  6. package/how-to-guides/auto-approve-and-auto-merge-dependency-update-prs.md +36 -0
  7. package/how-to-guides/build-a-workflow-of-only-custom-jobs.md +15 -0
  8. package/how-to-guides/change-the-workflow-environment.md +12 -0
  9. package/how-to-guides/configure-dependabot-updates.md +24 -0
  10. package/how-to-guides/configure-scala-steward.md +16 -0
  11. package/how-to-guides/control-ci-concurrency.md +30 -0
  12. package/how-to-guides/customize-the-generated-ci-jobs.md +54 -0
  13. package/how-to-guides/customize-the-generated-readme.md +36 -0
  14. package/how-to-guides/draft-releases-with-release-drafter.md +16 -0
  15. package/how-to-guides/enable-netlify-deploy-previews.md +42 -0
  16. package/how-to-guides/keep-the-workflow-in-sync.md +12 -0
  17. package/how-to-guides/publish-a-releases-docs-again.md +18 -0
  18. package/how-to-guides/regenerate-workflows-on-bot-prs.md +15 -0
  19. package/how-to-guides/set-job-timeouts.md +17 -0
  20. package/how-to-guides/test-against-several-scala-and-java-versions.md +101 -0
  21. package/index.md +25 -733
  22. package/package.json +1 -1
  23. package/reference/ci.md +148 -0
  24. package/reference/ecosystem.md +141 -0
  25. package/reference/githubactions.md +51 -0
  26. package/reference/index.md +15 -0
  27. package/reference/source.md +109 -0
  28. package/reference/website.md +103 -0
  29. package/sidebars.js +57 -3
  30. 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: "ZIO SBT",
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 `[![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-sbt/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/maven-central/v/dev.zio/zio-sbt-website_2.12_1.0.svg?label=Sonatype%20Release)](https://central.sonatype.com/artifact/dev.zio/zio-sbt-website_2.12_1.0) [![Sonatype Snapshots](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fcentral.sonatype.com%2Frepository%2Fmaven-snapshots%2Fdev%2Fzio%2Fzio-sbt-website_2.12_1.0%2Fmaven-metadata.xml&label=Sonatype%20Snapshot)](https://central.sonatype.com/repository/maven-snapshots/dev/zio/zio-sbt-website_2.12_1.0/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-sbt-website_2.12_1.0/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-sbt-website_2.12_1.0) [![ZIO SBT](https://img.shields.io/github/stars/zio/zio-sbt?style=social)](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).