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

Milestoner

link=badge.fury.io/rb/milestoner

image::badge.fury.io/rb/milestoner.svg[Gem Version]

link=www.alchemists.io/projects/code_quality

image::img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]

link=circleci.com/gh/bkuhlmann/milestoner

image::circleci.com/gh/bkuhlmann/milestoner.svg?style=svg[Circle CI Status]

Milestoner is a command line interface for crafting Git repository milestones (also known as tags or versions). Each milestone is a summary of all commits made since the last milestone. You can use Milestoner to inspect what is currently unreleased or create a new release via a single command. By having a tool, like Milestoner, you can quickly manage/automate releases in a consistent and reliable fashion. Milestoner also pairs well with https://www.alchemists.io/projects/git-lint[Git Lint] for further ensuring you have commit messages of high quality for your release notes.

toc::[]

Features

** Format: `+<major>.<minor>.<patch>+`. ** Example: `0.1.0`.

** Fixed ** Added ** Updated ** Removed ** Refactored

  • Ensures Git commit messages are alphabetically sorted.

  • Ensures duplicate Git commit messages are removed (if any).

  • Provides optional security for signing Git tags with www.gnupg.org[GnuPG] signing key.

Requirements

. A UNIX-based system. . www.ruby-lang.org[Ruby]. . www.gnupg.org[GnuPG].

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.

SECURITY OPTIONS:

--[no-]sign                          Sign with GPG key. Default: true.

.…

Examples:

source,bash

milestoner –config edit milestoner –config view

milestoner –help

milestoner –publish 0.1.0 milestoner –publish 0.1.0 –sign milestoner –publish 0.1.0 –no-sign

milestoner –status milestoner –version


Customization

This gem can be configured via a global configuration:

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

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

The default configuration is as follows:

source,yaml

:documentation:

:format: "md"

:git:

:commit: 
  :prefixes: 
    - Fixed
    - Added
    - Updated
    - Removed
    - Refactored
:tag: 
  :sign: false

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:

  • *Documenation Format*: Determines what format the status information should be rendered. Defaults to https://daringfireball.net/projects/markdown[Markdown] (i.e. `md`) but https://asciidoctor.org/docs/what-is-asciidoc[ASCII Doc] (i.e. `adoc`) is supported too.

  • *Git Commit 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: []`.

  • *Git Tag Sign*: Defaults to `false` but can be enabled by setting to `true`. When enabled, a Git tag will require GPG signing for enhanced security and include a signed signature as part of the Git tag. This is useful for public milestones where the author of a milestone can be verified to ensure milestone integrity/security.

Security

To securely sign your Git tags, install and configure 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 Git configuration in the `[user]` section. Example:

.…

user

signingkey = <your GPG key>

.…

Now, when publishing a new milestone (i.e. `+milestoner –publish <version> –sign+`), signing of your Git tag will happen automatically. You will be prompted for the GPG Passphrase each time but that is to be expected.

Development

To contribute, run:

source,bash

git clone github.com/bkuhlmann/milestoner.git 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


Versioning

Read https://semver.org[Semantic Versioning] for details. Briefly, it means:

  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

  • Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.

  • Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

Code of Conduct

Please note that this project is released with a CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By participating in this project you agree to abide by its terms.

Contributions

Read CONTRIBUTING.adoc[CONTRIBUTING] for details.

License

Read LICENSE.adoc[LICENSE] for details.

History

Read CHANGES.adoc[CHANGES] for details.

Credits

Engineered by https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].