bpg / awesome-scala-library.g8

Template for starting FP libraries ready to be published

Awesome Scala Library Template

This is a Giter8 template for creating libraries ready to be published.

NOTE: This project was started as a fork of https://github.com/alexandru/typelevel-library.g8, with some minor updates and improvements. But at this point I don't think I will be merging it back to the upstream, as I have quite a few specific changes.

• Usage
  • Setting Up GitHub (with main instead of master)
  • Configuration of Automatic Releases to Sonatype
• Sample Project
• Features
• Template license

Usage

Using sbt run the following in a terminal:

sbt new bpg/awesome-scala-library.g8

Setting Up GitHub

First initialize the local git repository, and do your first commit:

cd $project-folder/

git init

git commit -am 'Initial commit'

Create a new repository on GitHub, see github.com/new and add it as your origin:

git remote add origin https://github.com/$GITHUB_USERNAME/$GITHUB_REPOSITORY

git push -u origin main

Configuration of Automatic Releases to Sonatype

The created project already has workflows defined for building and releasing the library on Sonatype via GitHub Actions. For automated releases to work, you need to configure:

• GH_TOKEN — for automatically publishing the documentation microsite with the repo scope:
  • see GitHub's documentation
  • Quick link (click here)
• For publishing to Sonatype:
  • GPG_PASSPHRASE
  • GPG_PRIVATE_KEY
  • SONATYPE_USERNAME
  • SONATYPE_PASSWORD
  • See documentation at sbt-ci-release for generating these

Keep dependencies up to date

This template project, as well as created project, has a pre-configured Scala Steward GitHub Action that together with Mergify Bot keep dependencies up-to-date. For the action to work you also need secrets:

• GH_TOKEN
• GPG_PASSPHRASE
• GPG_PRIVATE_KEY

Release drafting

The created project has a pre-configured Release Drafter GitHub Action to draft a nicely looking release notes based on PR labels.

It uses some custom labels to classify PRs, see .github/release-drafter.yml for more details. The labels can be created with help of hub CLI using the script:

#!/bin/sh
REPO="bpg/my-awesome-library"

hub api /repos/${REPO}/labels -X POST -f 'name=dependency' -f 'description=Dependency update' -f 'color=a8f49c'
hub api /repos/${REPO}/labels -X POST -f 'name=skip-changelog' -f 'description=Do not include this PR in the changelog' -f 'color=ffffdd'
hub api /repos/${REPO}/labels -X POST -f 'name=breaking' -f 'description=Backward-incompatible change, may break existing API clients' -f 'color=e2b236'
hub api /repos/${REPO}/labels -X POST -f 'name=maintenance' -f 'description=Maintenance / technical debt' -f 'color=371596'
hub api /repos/${REPO}/labels -X POST -f 'name=major' -f 'color=666666'
hub api /repos/${REPO}/labels -X POST -f 'name=minor' -f 'color=666666'
hub api /repos/${REPO}/labels -X POST -f 'name=patch' -f 'color=666666'

Publish website

To publish the website to GitHub Pages, it is recommended that you first create the gh-pages branch:

git checkout --orphan gh-pages
git rm --cached -r .
touch index.html && git add index.html
git commit -am 'Initial commit'
git push --set-upstream origin gh-pages
git add .
git reset --hard HEAD
git checkout main

Sample Project

See sample library generated out of the box:

• github repository
• documentation website
• maven central artifacts (published via CI)

Features

• Build setup for multiple sub-projects
• Sane Scala compiler defaults for doing FP (including kind-projector and better-monadic-for)
• Continuous integration via GitHub Actions
  • With automated publishing to Sonatype!
• Usual contributing, code of conduct, license boilerplate
• Scala.js cross-compilation
• sbt-crossproject for managing the JVM / JS configuration
• sbt-unidoc for unifying the API documentation of the sub-projects
• sbt-doctest for testing the ScalaDoc
• sbt-microsites for building the documentation website, type checked via mdoc
• sbt-header for automatic copyright headers
• sbt-scalafmt default setup for auto-formatting
• sbt-tpolecat for sane Scalac compiler options with most linter options on
• sbt-ci-release for managing the versioning and the release to Sonatype
  • sbt-git setup for version management based on Git tags and SHAs
  • sbt-dynver a ready-made setup of sbt-git options for dynamic version management
  • sbt-sonatype for faster and easier releases
• sbt-scoverage for code coverage with sane setup
• Ammonite REPL for quickly trying new stuff, run via test:run
• ...

Template license

Cloned from scala/scala-seed, inspired by the build definition of Monix and by ChristopherDavenport/library.g8, another template with similar goals.

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this template to the public domain worldwide. This template is distributed without any warranty. See http://creativecommons.org/publicdomain/zero/1.0/.