Expublish

Automates semantic release versioning and best practices for elixir packages.

Explublish helps keeping a clean and trackable version history in a project, while providing a consistent and easy release experience to its maintainers. It was created with a continuous release process in mind and can be used to fully automate the release of new package versions.

What it does

Inspired by various release utilities that exist for different languages and ecosystems, Expublish provides a mix task that guarantees a clean and functioning project state before it performs the steps required to release a new package version following semantic versioning conventions.

Using mix expublish guarantees:

• a clean git working directory.
• passing tests.
• an increased version in mix.exs or version file.
• a new curated changelog entry.
• a new version git commit and tag.
• git push to given remote and branch.
• mix hex.publish to release the new package version and documentation to users.

Some of the steps can be opted out from and when not executed from CI, it's recommended to always execute a --dry-run before rerunning the expublish task without said option.

mix expublish supports various command-line options, check out the Cheatsheet and Reference pages.

Getting started

1. Follow the installation instructions.

2. For every new release, create a RELEASE.md containing a new changelog entry:

$ echo "- changelog entry one\n- changelog entry two" > RELEASE.md

3. Run mix expublish:

$ mix expublish.minor

Note that in case the push or publish step fail because of missing authentication or a failing network, the task must not be rerun. Instead run git push or mix hex.publish to finish releasing the new version.

Installation

See the Installation page to learn how to set up Expublish.

Cheatsheet

See the Cheatsheet page to get a quick overview on how to use the various options.

Version levels

See the Version levels page to learn how Expublish increases version levels.

Quick Reference

See the full Reference page to learn about all valid mix expublish task levels, options and defaults.

Usage: mix expublish.[level] [options]

level:
  major   - Publish next major version
  minor   - Publish next minor version
  patch   - Publish next patch version
  stable  - Publish current stable version from pre-release
  rc      - Publish release-candidate pre-release of next patch version
  beta    - Publish beta pre-release of next patch version
  alpha   - Publish alpha pre-release of next patch version

options:
  -d, --dry-run           - Perform dry run (no writes, no commits)
  --allow-untracked       - Allow untracked files during release
  --as-major              - Only for pre-release level
  --as-minor              - Only for pre-release level
  --disable-publish       - Disable hex publish
  --disable-push          - Disable git push
  --disable-test          - Disable test run
  --changelog-date-time   - Use date-time instead of date in new changelog entry
  --branch=string         - Remote branch to push to, default: "master"
  --remote=string         - Remote name to push to, default: "origin"
  --commit-prefix=string  - Custom commit prefix, default:  "Version release"
  --tag-prefix=string     - Custom tag prefix, default: "v"
  --version-file=string   - When working with a separate version file

Links and resources

• Hex.pm docs
• Keep a changelog
• SemVer specification
• Blog post on private hex auth
• Example github action