# Expublish

Automates semantic release versioning and best practices for elixir packages.

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
- Increased version in mix.exs
- A new curated changelog entry
- A new version git commit and tag
- Pushed changes to remote git and hex repositories

Explublish aims at keeping a clean and trackable version history of 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 as long as git and mix are available executables.

By default the task will **publish and push** the new package version to hex and
git respectively and when not executed from CI, it's recommended to
always perform a `--dry-run` before rerunning it 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\. Add `:expublish` to your mix dev dependencies and follow the short [Installation](./docs/ instructions.

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

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

This file is deleted after a successful release and should be inside your `.gitignore`.

3\. Run `mix expublish`:

$ mix expublish.minor

<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 for 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

Note on pre-releases: their next version level can be changed by using
one of the --as-major or --as-minor 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
  --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"

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

## Links and resources

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