alejandrohdezma / sbt-ci

Default workflow, documentation and root files for scala libraries

Version Matrix

Default workflow, documentation and root files for scala libraries


Introduction

This plugin generates default Github Actions workflows, documentation templates, configuration files, secrets and repository settings for @alejandrohdezma's Scala libraries repositories.

Installation

Add the following line to your plugins.sbt file:

addSbtPlugin("com.alejandrohdezma" % "sbt-ci" % "1.3.1")

Usage

Once the plugin has been installed just execute sbt generateCiFiles to automatically add all the documentation, workflows and settings files to the project. Once these files are committed it will automatically update the plugin (and therefore the files) by using Scala Steward.

What files does it generate?

Github Actions workflows

The Github Actions workflow can be found in the .github/workflows directory. If any of them need settings, they will live under .github.

File Copied as... Enabled on... Description
ci.yml .github/workflows/ci.yml Pushes to master and PRs Runs sbt ci-test on the project. This task should be added to the project as a command alias containing the necessary steps to compile, check formatters, launch tests and upload coverage (if necessary). An example of this alias can be found here. Also labels PRs automatically depending on the base branch following this configuration file (also generated as .github/pr-labeler.yml). On Scala Steward PRs it will launch formatters and this plugin's generateCiFiles task and push the results to the same PR. Finally it will merge Scala Steward that have succeed.
docs.yml .github/workflows/docs.yml Releases and manually Runs sbt ci-docs on the project and pushes a commit with the changes. The ci-docs task should be added to the project as a command alias containing the necessary steps to update documentation (re-generate docs files, publish websites, update headers...). And example of this alias can be found here.
release.yml .github/workflows/release.yml Releases and pushes to master Creates a release of the project by running sbt ci-publish. This task should be added to the project as a command alias containing the necessary steps to do a release. An example of this alias can be found here.
scala-steward.yml .github/workflows/scala-steward.yml By cron and manually Runs Scala Steward periodically on the project (with the current configuration it will launch at 7:00 am (CET) on Monday, Wednesday and Friday).
draft-next-release.yml .github/workflows/draft-next-release.yml Merging pull-requests This workflow drafts your next release notes as pull requests are merged into master. Given the current configuration, it creates categories depending on the PRs labels. An example of a generated release body can be found here.

All the workflows need specific secrets to be enabled in the repository.

Documentation templates

These documentation templates are expected to be used in conjunction with mdoc. Some of them use special mdocVariables that can be automatically included by using sbt-github-mdoc plugin. All of these templates should be compiled and processed into their final files when launching sbt ci-docs in the docs.yml workflow.

File Copied as... Needs mdocVariables? Description Compiled example
AUTHORS.md docs/AUTHORS.md COLLABORATORS & CONTRIBUTORS Contains both the list of contributors and project collaborators. AUTHORS.md
CODE_OF_CONDUCT.md docs/CODE_OF_CONDUCT.md Nope Code of conduct for the repository. Links to the Scala Code of Conduct. CODE_OF_CONDUCT.md
CONTRIBUTING.md docs/CONTRIBUTING.md NAME, REPO, ORG_NAME & ORG_EMAIL Explains how a user can contribute to the project. CONTRIBUTING.md
LICENSE.md docs/LICENSE.md YEAR_RANGE & COPYRIGHT_OWNER Default license for the project. LICENSE.md
NOTICE.md docs/NOTICE.md NAME, YEAR_RANGE, ORG_NAME & LICENSE Contains the copyright notices for the organization/owner. NOTICE.md

Root files

These files will be copied to the root directory of the remote project:

File Description
.gitignore Typical git ignoring configurations for a Scala project.

How are files generated?

After each release of this plugin Scala Steward will update the plugin version in all the repositories that use it and when the ci.yml workflow workflow gets launched, it will execute sbt generateCiFiles (creating, updating or deleting files handled by the plugin).

What settings spread?

The following repository settings will be enforced on every repository:

  • Wikis will be disabled.
  • Branches will be deleted after merge them.
  • The default branch will be master.
  • Squash merging will be enabled.
  • Merge commits will be enabled.
  • Rebase merging will be disabled.

It will also spread a set of labels to be used on issues & pull-requests (detailed here).

Lastly it will add branch protection on the master branch requiring:

  • At least 1 pull request review from a code-owner.
  • Pull-request branches should be up-to-date with master.
  • The ci.yml workflow should pass correctly.

Admins will be allowed to bypass this protection and merge PRs on any condition.