The letter A styled as Alchemists logo. lchemists

Putin's War on Ukraine - Watch President Zelenskyy's speech and help Ukraine fight against the senseless cruelty of a dictator!

Brooke Kuhlmann's Avatar Brooke Kuhlmann
Published September 6, 2015 Updated March 7, 2023
Milestoner Icon

Milestoner

15.2.1

Circe CI Status. Alchemists Style Guide. Git Badge Sponsor Badge

Milestoner is a command line interface for crafting Git repository tags (milestones) using 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:

  • Git Lint - Ensures your commit messages are of high quality which feed into the release notes built by Milestoner.

  • Rubysmith - Use Milestoner to automate the publishing of new or existing Ruby project versions.

  • Gemsmith - Is built on top of Milestoner and is used to publish new Ruby gem versions.

Features

  • Uses Versionaire for 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 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

  1. A UNIX-based system.

  2. Ruby.

  3. GnuPG (optional).

Setup

To install, run:

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:

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 XDG environment variables.

The default configuration is as follows:

: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 ASCII Doc (i.e. adoc) but 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 GPG:

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 GPG Agent in the background (highly recommend).

Development

To contribute, run:

git clone https://github.com/bkuhlmann/milestoner
cd milestoner
bin/setup

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

bin/console

Tests

To test, run:

bundle exec spec

License

Security

Code of Conduct

Contributions

Versions

Community

Credits