[![Coverage Status](](

# 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](./docs/ and [Reference](./docs/ pages.

<span id="getting-started"></span>

## Getting started

1\. Follow the [installation](./docs/ instructions.

2\. For every new release, create a `` containing a new changelog entry:

$ echo "- changelog entry one\n- changelog entry two" >

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](./docs/ page to learn how to set up Expublish.

<span id="version-levels"></span>

<span id="cheatsheet"></span>

## Cheatsheet

See the [Cheatsheet](./docs/ page to get a quick overview on how to use the various options.

<span id="version-levels"></span>

## Version levels

See the [Version levels](./docs/ page to learn how Expublish increases version levels.

<span id="quick-reference"></span>

## Quick Reference

See the full [Reference](./docs/ page to learn about all valid `mix expublish`
task levels, options and defaults.

Usage: mix expublish.[level] [options]

  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

  -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

<span id="links-and-resources"></span>

## Links and resources

- [ docs](
- [Keep a changelog](
- [SemVer specification](
- [Blog post on private hex auth](
- [Example github action](