alejandrohdezma / sbt-github

SBT plugin to read several settings from Github

GitHub

SBT plugin to read several settings from Github

This plugin enables several settings automatically by downloading them from Github:

  • homepage: Retrieved from the Github repository's information.
  • developers: A list containing the repository collaborators.
  • description: Retrieved from the Github repository.
  • licenses: Retrieved from the Github repository.
  • contributors: The list of repository contributors. This list will not include contributors set in excludedContributors.
  • collaborators: The list of repository collaborators who are also contributors. This list will always include collaborators set in extraCollaborators.
  • startYear: Extracted from the repository creation date.
  • yearRange: A year range that goes from startYear to the current year.
  • organizationName: The repository organization name or the owner's name if populateOrganizationWithOwner is set to true.
  • organizationEmail: The repository organization email or the owner's email if populateOrganizationWithOwner is set to true.
  • organizationHomepage: The repository organization homepage or the owner's homepage if populateOrganizationWithOwner is set to true.

Installation

Add the following line to your plugins.sbt file:

addSbtPlugin("com.alejandrohdezma" %% "sbt-github" % "0.5.1")

If you use mdoc there's also available an mdoc integration module

If you use sbt-header there's also available an sbt-header integration module

Configuration

By default, the plugin only downloads the information if an environment variable named DOWNLOAD_INFO_FROM_GITHUB is present in the system SBT is running (the content of the variable is not important). This behavior can be tweaked by using the downloadInfoFromGithub setting:

ThisBuild / downloadInfoFromGithub := true

Download owner information if it doesn't have an organization

sbt-github will populate organizationName, organizationEmail and organizationHomepage with information from repository's organization. In case the repository doesn't belong to an organization those settings will be populated with the owner's information. You can disable this functionality by setting populateOrganizationWithOwner to false:

ThisBuild / populateOrganizationWithOwner := false

Excluding contributors

The contributors setting is populated with the information extracted from the repository contributor list. This list will include all Github users who have contributed to the repository, which is not what we always want (including bots, for example). You can exclude certain Github users by using the excludedContributors setting.

ThisBuild / excludedContributors += "my-bot"

In addition you can exclude contributors whose Github ID matches some pattern using regex:

// Will exclude: my-company[bot], external-app[bot]
ThisBuild / excludedContributors += """.*\[bot\]"""

By default the following list is excluded:

  • scala-steward
  • .*[bot]
  • traviscibot

Adding extra collaborators

The collaborators and developers settings are populated with the information extracted from the repository collaborator list (who are also contributors). If you want to include extra collaborators, you can use the extraCollaborators setting:

ThisBuild / extraCollaborators += Collaborator("alejandrohdezma", "Alejandro Hernández", "https://github.com/alejandrohdezma")

If you don't want to provide all the details for an extra collaborator, you can use the Collaborator.github constructor and let sbt-github download its information for you:

ThisBuild / extraCollaborators += Collaborator.github("alejandrohdezma")

Github API token

For this plugin to work you'll need to add an environment variable named GITHUB_TOKEN with a personal access token.

If you are using Github Actions, you can use the provided GITHUB_TOKEN.

Integrations

mdoc integration

If you use mdoc for creating your documentation you can benefit from our mdoc module which provides several bunches of mdocVariables already pre-filled with values extracted from Github to any project that adds the MdocPlugin to replace them in the documentation. To use it, just add the following line to your plugins.sbt file

addSbtPlugin("com.alejandrohdezma" %% "sbt-github-mdoc" % "0.5.1")

Important! So we don't force a version of mdoc, it is requested as a Provided dependency so you'll need to provide your own version of mdoc following its own tutorial.

The plugin provides the following mdocVariables:

Variable Content
VERSION Set to the value of the version setting by removing the timestamp part (this behavior can be disabled using the removeVersionTimestampInMdoc setting)
CONTRIBUTORS Set to the value of the contributors setting, containing the list of repository contributors in markdown format
COLLABORATORS Set to the value of the collaborators setting, containing the list of repository collaborators in markdown format
NAME Set to the project's name
LICENSE Set to the license's name
ORG_NAME Set to the value of organizationName setting (Github's organization name or owner's in case organization is empty and populateOrganizationWithOwner is true)
ORG_EMAIL Set to the value of organizationEmail setting (Github's organization email, or owner's in case organization is empty and populateOrganizationWithOwner is true)
ORG_URL Set to the value of organizationHomepage setting (Github's organization homepage or owner's in case organization is empty and populateOrganizationWithOwner is true)
REPO Set to the repository's path: "owner/repo"
START_YEAR Set to the value of the startYear setting
YEAR_RANGE Set to the value of the yearRange setting

sbt-header integration

If you use sbt-header for creating/updating your file headers according to your project's license you can benefit from our sbt-github-header module which pre-fills header template with downloaded Github values. To use it, just add the following line to your plugins.sbt file

addSbtPlugin("com.alejandrohdezma" %% "sbt-github-header" % "0.5.1")

Important! So we don't force a version of sbt-header, it is requested as a Provided dependency so you'll need to provide your own version of sbt-header.

What does this integration do?

Populates the headerLicense setting from sbt-header with values extracted from Github by SbtGithubPlugin:

  • Year: The information stored in yearRange.
  • Copyright Owner: The information stored in copyrightOwner, provided by the own integration plugin. Defaults to organizationName value if there is no value for organizationHomepage or organizationName <organizationHomepage> if there is.

The licenseStyle setting can be used to tweak the style of the autogenerated headers. Defaults to Detailed.

Example

For example, given a project with:

  • an Apache-2.0 license...
  • given that the repository start year is 2019...
  • that the organization name is Alejandro Hernández...
  • and the organization homepage is https://github.com/alejandrohdezma

The following headers will be added to every file:

/*
 * Copyright (c) 2019-2020 Alejandro Hernández <https://github.com/alejandrohdezma>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */