:toc: macro :toclevels: 5 :figure-caption!: = Milestoner [link=http://badge.fury.io/rb/milestoner] image::https://badge.fury.io/rb/milestoner.svg[Gem Version] [link=https://www.alchemists.io/projects/code_quality] image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide] [link=https://circleci.com/gh/bkuhlmann/milestoner] image::https://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 link: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 * Uses link:https://www.alchemists.io/projects/versionaire[Versionaire] for link:https://semver.org[Semantic Versioning]. ** Format: `+..+`. ** 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://www.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). * Provides optional security for signing Git tags with https://www.gnupg.org[GnuPG] signing key. == Requirements . A UNIX-based system. . https://www.ruby-lang.org[Ruby]. . https://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 https://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 link:https://daringfireball.net/projects/markdown[Markdown] (i.e. `md`) but link: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 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: `++` * Email: `++` * 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 = .... Now, when publishing a new milestone (i.e. `+milestoner --publish --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 https://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 link: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 link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By participating in this project you agree to abide by its terms. == Contributions Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details. == License Read link:LICENSE.adoc[LICENSE] for details. == History Read link:CHANGES.adoc[CHANGES] for details. == Credits Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].