: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 useMilestoner
to inspect what is currently unreleased or create a new release via a single command. By having a tool, likeMilestoner
, 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¶ ↑
-
Uses https://www.alchemists.io/projects/versionaire[Versionaire] for 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 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 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].
-
-
-
-