arron-green / typelevel-library.g8

Template for starting FP libraries ready to be published

Typelevel Library Template

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

• 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 --sbt-version 1.3.13 new alexandru/typelevel-library.g8

Setting Up GitHub (with main instead of master)

NOTE: the template is set to use main as the default branch, instead of master and this is reflected in the README pixels.

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

cd $project-folder/

git init

git branch -m master main

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

Next in GitHub:

• Navigate to your repository > Settings > Branches
• Select main as your default branch
• Update your branch protection rules
• Navigate to Code > Branches and delete master

(Hoping GitHub will soon make this easier)

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:
  • PGP_PASSPHRASE
  • PGP_SECRET
  • SONATYPE_USERNAME
  • SONATYPE_PASSWORD
  • See documentation at sbt-ci-release for generating these

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
• ...

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/.