Note

All of my GitHub repositories have been archived and will be migrated to Codeberg as I next work on them. This repository either now lives, or will live, at:

https://codeberg.org/pbrisbin/semantic-release-stack-upload

If you need to report an Issue or raise a PR, and this migration hasn't happened yet, send an email to me@pbrisbin.com.

semantic-release-stack-upload

semantic-release plugin to publish a Haskell package to Hackage using stack upload.

Requirements

1. Hpack in use, e.g. package.yaml exists

Features

1. Supports multi-package projects
2. Supports PVP + SemVer versioning style
3. Supports stack upload behaviors like --candidate and --pvp-bounds

Steps

Step	Description
verifyConditions	verify the environment variable HACKAGE_KEY is set and package.yaml exists
verifyRelease	Update the version in package.yaml if PREPARE_IN_VERIFY=1
prepare	Update the version in package.yaml
publish	run stack upload to publish the package

Environment variables

Variable	Description	Required
HACKAGE_KEY	API token for hackage	true
PREPARE_IN_VERIFY	Should we update package.yaml in verifyRelease?	false

Prepare in Verify and dryRun

If the PREPARE_IN_VERIFY environment variable is set to 1, we will perform what is usually done in prepare as part of verifyRelease, i.e. update the package.yaml file with the next version.

This is useful if, for example, you are compiling a binary that includes a version sub-command or --version flag that uses the package version through the generated Paths_ module. If package.yaml is not updated before this compilation, the compiled-in version will be wrong.

To accomplish a pre-compile update, you can run semantic-release in dryRun mode with PREPARE_IN_VERIFY=1, build your assets, then run it again to actually release.

Install

With npm:

npm install semantic-release-stack-upload -D

With yarn:

yarn add semantic-release-stack-upload --dev

GitHub Actions

- id: release
  uses: cycjimmy/semantic-release-action@v4
  with:
    extra_plugins: |
      semantic-release-stack-upload
  env:
    GITHUB_TOKEN: ${{ github.token }}
    HACKAGE_KEY: ${{ secrets.HACKAGE_KEY }}

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "semantic-release-stack-upload",
      {
        "pvpBounds": "lower",
        "stripSuffix": true
      }
    ]
  ]
}

Configuration

All options are optional.

candidate

Default: undefined

Upload a release candidate (use the --candidate option). If this is undefined, prerelease branches upload candidates and release branches don't.

ignoreCheck

Default: false

Do not check packages for common mistakes (use the --ignore-check option).

item

Default: .

A relative path to a package directory to upload.

Note

This also determines where the package.yaml file is expected.

pvpBounds

Default: none

Automatically add PVP bounds to dependencies based on the active resolver at time of upload (use the --pvp-bounds option). One of none, lower, upper, or both.

Note

You may wish to set STACK_YAML to inform this.

stripSuffix

Default: false

Whether to strip prerelease suffixes from versions. For example, when true, a version like 1.0.0-rc.plugin.1 will be released as 1.0.0.

versionPrefix

Default: undefined

A prefix to apply to the version when used for the package. This allows the project to use SemVer (e.g. 1.0.0), but release PVP-compliant packages by adding a prefix like "0." to result in 0.1.0.0

If not defined, and your checked-in package.yaml uses a version matching ^{prefix}{semver}$, then {prefix} will be used. For example, setting a version of 0.0.0.0 will mean "0." will be used as prefix. This is the recommended configuration.

workingDirectory

Default: undefined

Change to this directory before doing anything.