:toc: macro
:toclevels: 5
:figure-caption!:

= Milestoner

Milestoner is a command line interface for crafting Git repository tags (milestones) using
link:https://semver.org[semantic versions]. Each milestone is a summary of all commits made since
the last milestone. You can use Milestoner to inspect what is currently pending or create a new
release via a single command. By having a tool, like Milestoner, you can automate releases in a
consistent and reliable fashion. Milestoner pairs well with the following gems:

- link:https://alchemists.io/projects/git-lint[Git Lint] - Ensures your commit messages are of
  high quality which feed into the release notes built by Milestoner.
- link:https://alchemists.io/projects/rubysmith[Rubysmith] - Use Milestoner to automate the
  publishing of new or existing Ruby project versions.
- link:https://alchemists.io/projects/gemsmith[Gemsmith] - Is built on top of Milestoner and is
  used to publish new Ruby gem versions.

toc::[]

== Features

* Uses link:https://alchemists.io/projects/versionaire[Versionaire] for
  link:https://semver.org[Semantic Versioning].
** Format: `+<major>.<minor>.<patch>+`.
** Example: `+0.1.0+`.
* Ensures Git commits since last tag (or initialization of repository) are included.
* Ensures Git commit messages are grouped by prefix, in order defined. For more details, see
  link:https://alchemists.io/projects/git-lint/#_commit_subject_prefix[Git Lint Commit Subject
  Prefix] for details. Defaults (can be customized):
** Fixed
** Added
** Updated
** Removed
** Refactored
* Ensures Git commit messages are alphabetically sorted.
* Ensures duplicate Git commit messages are removed (if any).

== Requirements

. A UNIX-based system.
. https://www.ruby-lang.org[Ruby].
. https://www.gnupg.org[GnuPG] (optional).

== Setup

To install, run:

[source,bash]
----
gem install milestoner
----

== Usage

=== Command Line Interface (CLI)

From the command line, type: `milestoner --help`

....
USAGE:
  -c, --config ACTION                      Manage gem configuration. Actions: edit || view.
  -h, --help                               Show this message.
  -P, --publish VERSION                    Tag and push milestone to remote repository.
  -s, --status                             Show project status.
  -v, --version                            Show gem version.
....

Examples:

[source,bash]
----
milestoner --config edit
milestoner --config view
milestoner --help
milestoner --publish 0.1.0
milestoner --status
milestoner --version
----

=== Customization

This gem can be configured via a global configuration:

....
~/.config/milestoner/configuration.yml
....

It can also be configured via https://alchemists.io/projects/xdg[XDG] environment variables.

The default configuration is as follows:

[source,yaml]
----
:documentation:
  :format: "adoc"
:prefixes:
  - Fixed
  - Added
  - Updated
  - Removed
  - Refactored
----

Feel free to take this default configuration, modify, and save as your own custom
`+configuration.yml+`.

The `+configuration.yml+` file can be configured as follows:

* *Documentation Format* (i.e. `documentation`): Determines what format the release notes should be
  rendered as. This effects both status information from the command line and the release notes
  embedded within the body of a Git tag. Defaults to
  link:https://asciidoctor.org/docs/what-is-asciidoc[ASCII Doc] (i.e. `adoc`) but
  link:https://daringfireball.net/projects/markdown[Markdown] (i.e. `md`) is supported too.
* *Git Commit Prefixes* (i.e. `prefixes`): Should the default prefixes not be desired, you can
  define Git commit prefixes that match your style. _NOTE: Prefix order is important with the first
  prefix defined taking precedence over the second and so forth._ Special characters are allowed for
  prefixes but should be enclosed in quotes. To disable prefix usage completely, use an empty array.
  Example: `:prefixes: []`.

== Security

To securely sign your Git tags, install and configure https://www.gnupg.org[GPG]:

[source,bash]
----
brew install gpg
gpg --gen-key
----

When creating your GPG key, choose these settings:

* Key kind: RSA and RSA (default)
* Key size: 4096
* Key validity: 0
* Real Name: `+<your name>+`
* Email: `+<your email>+`
* Passphrase: `+<your passphrase>+`

To obtain your key, run the following and take the part after the forward slash:

....
gpg --list-keys | grep pub
....

Add your key to your global (or local) Git configuration and ensure GPG signing for your tag is
enabled. Example:

....
[tag]
  gpgSign = true
[user]
  signingkey = <your GPG key>
....

Now, when publishing a new milestone (i.e. `milestoner --publish <version>`), the signing of your
Git tag will happen automatically. You will be prompted for the GPG Passphrase each time unless you
are running the
link:https://gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT[GPG
Agent] in the background (highly recommend).

== Development

To contribute, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/milestoner
cd milestoner
bin/setup
----

You can also use the IRB console for direct access to all objects:

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bundle exec spec
----

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/projects/milestoner/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].