milestoner icon indicating copy to clipboard operation
milestoner copied to clipboard

A command line interface for automated Git repository milestones.

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

:ascii_doc_link: link:https://asciidoctor.org/docs/what-is-asciidoc[ASCII Doc] :cff_link: link:https://github.com/citation-file-format/ruby-cff[CFF] :etcher_link: link:https://alchemists.io/projects/etcher[Etcher] :gem_specification_link: link:https://guides.rubygems.org/specification-reference[Gem Specification] :gemsmith_link: link:https://alchemists.io/projects/gemsmith[Gemsmith] :git_commit_anatomy_link: link:https://alchemists.io/articles/git_commit_anatomy[Git Commit Anatomy] :git_link: link:https://git-scm.com[Git] :git_lint_link: link:https://alchemists.io/projects/git-lint[Git Lint] :hanami_link: link:https://hanamirb.org[Hanami] :hanami_views_link: link:https://alchemists.io/articles/hanami_views[Hanami Views] :hanamismith_link: link:https://alchemists.io/projects/hanamismith[Hanamismith] :lode_link: link:https://alchemists.io/projects/lode[Lode] :markdown_link: link:https://daringfireball.net/projects/markdown[Markdown] :ruby_link: link:https://www.ruby-lang.org[Ruby] :rubygems_link: link:https://rubygems.org[RubyGems] :rubysmith_link: link:https://alchemists.io/projects/rubysmith[Rubysmith] :runcom_link: link:https://alchemists.io/projects/runcom[Runcom] :strict_semantic_versioning_link: link:https://alchemists.io/articles/strict_semantic_versioning[Strict Semantic Versioning] :string_formats_link: link:https://ruby-doc.org/3.3.0/format_specifications_rdoc.html[String Formats] :versionaire_link: link:https://alchemists.io/projects/versionaire[Versionaire] :xdg_link: link:https://alchemists.io/projects/xdg[XDG]

= Milestoner

Milestoner is a pure {git_link} based Command Line Interface (CLI) for software deployment automation that is agnostic of the programming language or source control service you use (i.e. GitHub, GitLab, Bitbucket, etc). Each milestone (i.e. {git_link} tag) includes the automatic generation of feature rich release notes sourced from the {git_link} commits that make up the milestone. Finally, each milestone adheres to {strict_semantic_versioning_link} so your milestones remain consistent.

You can use Milestoner to inspect the current state of the next milestone, celebrate the team members that contribute to each milestone, and share information with stakeholders with minimal effort. By having a tool, like Milestoner, you can automate software releases in a consistent and reliable fashion. 🎉

Milestoner pairs well with the following gems:

  • {git_lint_link}: Lints each {git_link} commit to ensure they are of high quality for historic inspection and release note generation.
  • {rubysmith_link}: Automates building new {ruby_link} projects.
  • {gemsmith_link}: Automates building new {rubygems_link} projects.
  • {hanamismith_link}: Automates building new {hanami_link} projects.

toc::[]

== Screenshots

ASCII Doc Format (i.e. milestoner build --format ascii_doc)

image:https://alchemists.io/images/projects/milestoner/screenshots/build-ascii_doc.png[Usage,width=787,height=257,role=focal_point]

Markdown Format (i.e. milestoner build --format markdown)

image:https://alchemists.io/images/projects/milestoner/screenshots/build-markdown.png[Usage,width=765,height=257,role=focal_point]

Stream Format (i.e. milestoner build --format stream)

image:https://alchemists.io/images/projects/milestoner/screenshots/build-stream.png[Usage,width=464,height=280,role=focal_point]

Web Format (i.e. milestoner build --format web)

image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-collapsed.png[Usage,width=998,height=409,role=focal_point]

image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-expanded.png[Usage,width=983,height=701,role=focal_point]

== Features

  • Uses {versionaire_link} for {strict_semantic_versioning_link}. Example: ** Format: +<major>.<minor>.<patch>+. ** Example: 0.0.0.
  • Ensures {git_link} commits since last tag (or initialization of repository) are included in the release notes.
  • Ensures {git_link} commit messages are grouped by prefix, in order defined, for categorization. For more details, see link:https://alchemists.io/projects/git-lint/#_commit_subject_prefix[Git Lint Commit Subject Prefix]. Defaults (can be customized): ** image:https://alchemists.io/images/projects/milestoner/icons/commits/fixed.png[Fixed] Fixed ** image:https://alchemists.io/images/projects/milestoner/icons/commits/added.png[Added] Added ** image:https://alchemists.io/images/projects/milestoner/icons/commits/updated.png[Updated] Updated ** image:https://alchemists.io/images/projects/milestoner/icons/commits/removed.png[Removed] Removed ** image:https://alchemists.io/images/projects/milestoner/icons/commits/refactored.png[Refactored] Refactored
  • Ensures {git_link} commit messages are alphabetically sorted for release note categorization and readability.
  • Provides automatic versioning based on last {git_link} tag and current commit trailers. See {git_commit_anatomy_link} for details.
  • Supports multiple release note build formats: {ascii_doc_link}, {markdown_link}, Stream (console), and Web (HTML). Each are fully customizable via your personal {xdg_link} configuration and {hanami_views_link}.

== Requirements

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

== Setup

To install with security, run:

[source,bash]

💡 Skip this line if you already have the public certificate installed.

gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem) gem install milestoner --trust-policy HighSecurity

To install without security, run:

[source,bash]

gem install milestoner

== Usage

=== Command Line Interface (CLI)

From the command line, type: milestoner --help

image:https://alchemists.io/images/projects/milestoner/screenshots/usage.png[Usage,width=670,height=412,role=focal_point]

=== Customization

This gem can be configured via a global configuration:

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

It can also be configured via {xdg_link} environment variables.

The default configuration is:

[source,yaml]

avatar: domain: https://avatars.githubusercontent.com uri: "%s/u/%s" build: format: web layout: page root: tmp/milestone commit: categories: - emoji: ✅ label: Fixed - emoji: 🟢 label: Added - emoji: 🔼 label: Updated - emoji: ⛔️ label: Removed - emoji: 🔁 label: Refactored domain: https://github.com format: asciidoc uri: "%s/%s/%s/commit/%s" generator: label: uri: version: profile: domain: https://github.com uri: "%s/%s" project: author: description: generator: label: name: owner: uri: version: review: domain: https://github.com uri: "%s/%s/%s/pulls/%s" tracker: domain: https://github.com uri: "%s/%s/%s/issues/%s"

The above can be customized as follows:

  • avatar: Manages team member avatar information. ** domain: Required. The domain of your team member avatars. Default: GitHub. ** uri: Required. The URI format for linking to avatars as formatted using {string_formats_link}. Default: GitHub. The id is dynamically calculated via the external_id of the user stored in the {lode_link} cache.
  • build: Manages release note builds. ** format: Required. The build output format. Multiple formats are supported. Default: web. ** layout: Required. The layout used by {hanami_views_link} when building release notes. Default: page. ** root: Required. The output location. This can be a relative or absolute path. Defaults to the tmp directory of your current project. The path is automatically created if missing.
  • commit: Manages commit categories, emojis, and hyperlinks. ** categories: Required. By default, only five categories are supported which pairs well with the {git_lint_link} gem. Category order is important with the first taking precedence over the second and so forth. Special characters are allowed for prefixes but should be enclosed in quotes. To disable categories, use an empty array. Example: categories: []. *** emoji: Required. The emoji associated with the label for output purposes. Used by the {ascii_doc_link}, {markdown_link}, and stream build formats. Defaults to the provided emojis. *** label: Required. Allows you to customize the category label. All commits are grouped by label which equates to the prefix, or first word, used in each commit message. The defaults pair well with the {git_lint_link} gem. Defaults to the provided labels. ** domain: Required. The {git_link} repository domain for all commits. Default: GitHub. ** format: Required. Defines the default format used for rendering commit messages unless specified in the commit trailer metadata which takes higher precedence. Default: {ascii_doc_link}. ** uri: Required. The URI format for linking to commits as formatted using {string_formats_link}. Default: GitHub. The id is dynamically calculated via the commit SHA of each commit analyzed at runtime.
  • generator: Manages generator information. ** label: Required. The label of the generator used for all software milestones. Default: Milestoner. ** uri: Required. The URI of the generator used for all software milestones. Defaults to Milestoner's homepage URL as provided by the {gem_specification_link} of this project. ** version: Required. The version of the generator used for all software milestones. Defaults to Milestoner's current version as provided by the {gem_specification_link} of this project.
  • profile: Manages team member profile information. ** domain: Required. The domain of your {git_link} repository. Default: GitHub. ** uri: Required. The URI format for linking to profiles as formatted using {string_formats_link}. The id is dynamically calculated via the handle of the user stored in the {lode_link} cache. Default: GitHub.
  • project: Manages project information. ** author: Required. The project author. Dynamically calculated by the {etcher_link} gem in the following order: This value or {git_link} configuration user name. ** description: Optional. The project description. Dynamically calculated by the {etcher_link} gem in the following order: This value, {gem_specification_link} summary, or {cff_link} abstract. ** generator: ⚠️ Deprecated and will be removed in the next major version. Please use the generator configuration section mentioned above instead. ** label: Optional. The project label. Dynamically calculated by the {etcher_link} gem in the following order: This value, {gem_specification_link} metadata label, or {cff_link} title. ** name: Required. The project name. Dynamically calculated by the {etcher_link} gem in the following order: This value or {gem_specification_link} name. ** owner: Optional. The project owner. This is your source code organization or user handle. Used when formatting URLs (mentioned above). Despite being optional, it is strongly recommended you configure this value so all links are formatted properly. ** uri: Optional. The project URI. Dynamically calculated by the {etcher_link} gem in the following order: This value or {gem_specification_link} homepage. ** version: Required. The project version. Dynamically calculated based on the last {git_link} tag of your project and {git_link} Milestone commit trailer metadata. The default is: 0.0.0. For more on this see, the Automatic Versioning section below. You can configure a value but, keep in mind, the value will be used for all deployments and release notes. Better to let this gem compute this for you.
  • review: Manages code review information. ** domain: Required. The domain of your code review service. Default: GitHub. ** uri: Required. The URI format for linking to code reviews as formatted using {string_formats_link}. Default: GitHub. The id is currently a placeholder for future feature support when API support is added. For now this links to all code reviews with the goal to link to individual code reviews based on issue tracker metadata from {git_link} commit trailers.
  • tracker: Required. Allows you to customize the issue tracker service you are using. Default: GitHub. ** domain: Required. The domain of your issue tracker service. Default: GitHub. ** uri: Required. The URI format for linking to issues as formatted using {string_formats_link}. Default: GitHub. The id is dynamically calculated via the commit Issue trailer as linted by {git_lint_link}.

💡 If you ever need to know what your current configuration looks like you can jump into your applications IRB console and inspect Milestoner::Container[:configuration] to see full details.

=== Config

image:https://alchemists.io/images/projects/milestoner/screenshots/usage-config.png[Usage,width=632,height=352,role=focal_point]

Milestoner can be configured via the command line using: milestoner config. This allows you to create, edit, view, and/or delete your global or local configuration as desired. The configuration is managed by the {runcom_link} gem which is built atop the {xdg_link} gem for managing global or local configurations. Please read the documentation of each gem to learn more.

=== Cache

image:https://alchemists.io/images/projects/milestoner/screenshots/usage-cache.png[Usage,width=625,height=318,role=focal_point]

Milestoner's cache allows you to enrich user information (i.e. authors, collaborators, etc) by storing information in a PStore database as managed by the {lode_link} gem. Cache location, as with the Config, is managed by the {runcom_link} gem.

User information should be sourced from whatever service you use for managing your source code. For example, when using GitHub, your workflow might look like this:

[source,bash]

milestoner cache --list

🟢 Listing users...

🟢 No users found.

milestoner cache --create "111,jsmith,Jane Smith"

🟢 Created: "Jane Smith"

milestoner cache --create "222,jdoe,John Doe"

🟢 Created: "John Doe"

milestoner cache --create "333,jgrey,Jill Grey"

🟢 Created: "Jill Grey"

milestoner cache --list

🟢 Listing users...

111, jsmith, Jane Smith

222, jdoe, John Doe

333, jgrey, Jill Grey

milestoner cache --delete "Jill Grey" 🟢 Deleted: "Jill Grey".

milestoner cache --list

🟢 Listing users...

111, jsmith, Jane Smith

222, jdoe, John Doe

milestoner cache --info

🟢 Path: /Users/demo/.cache/milestoner/database.store.


💡 Use +https://api.github.com/users/<handle>+ to acquire the external ID for any GitHub user.

Once team member information is stored in your cache, you'll be able to build release notes which automatically link to GitHub user information without constantly hitting the GitHub API. Users are identified by name so the full author name used for each commit message needs to match the same user name as stored in your source repository hosting service.

=== Build

image:https://alchemists.io/images/projects/milestoner/screenshots/usage-build.png[Usage,width=679,height=437,role=focal_point]

The build command allows you to quickly build release notes to check the current status of your project or deploy a new milestone. By default, the build command uses either the default or custom configuration as documented in the Configuration section above. This means, when using the defaults, you can immediately build the release notes for your project in a temporary directory:

[source,bash]

milestoner build --format web

🟢 Building milestone...

🟢 Milestone built: /Users/bkuhlmann/Engineering/OSS/milestoner/tmp/milestone


💡 The above command is so useful that I use the following msb (i.e. Milestoner Build) Bash alias: rm -rf tmp/milestone && milestoner build --format html && open tmp/milestone/index.html. This allows me to quickly rebuild release notes for any project and immediately view them in my default browser.

Check out the help documentation (i.e. milestoner build --help) for addition usage that explains what command line options you can use to overwrite the current configuration.

==== Automatic Versioning

As mentioned earlier, the calculation of version information happens automatically for you based on your last {git_link} tag and any {git_link} commit trailer metadata used. If none of this information is present, then the default version of 0.0.0 is used instead. All of this information is available to you via the following command:

[source,bash]

milestoner build --help

Running the above will dynamically show you latest version information -- along with help documentation -- in case you have doubts. You can use this as a status check as well. If you don't want to use the automatic version, you can override by using the --version option when building. Example:

[source,bash]

Uses automatic version.

milestoner build --format stream

Uses manual version.

milestoner build --format stream --version 1.2.3

By default, automatic versioning is based on your last known {git_link} tag and the version is bumped based on {git_link} commit trailer information from untagged commits (i.e. those commits created since the last tag). All of this is managed via the {versionaire_link} gem. To ensure automatic versioning works properly, you only need to add the Milestone {git_link} commit trailer with a value of: patch, minor, or major. Here's an example assuming you have published Version 1.0.0:

....

First commit.

Milestone: patch

Second commit.

Milestone: minor

Third commit

Milestone: patch ....

Given the above, the resulting version would be: 1.1.0. This is because the highest milestone was a minor milestone. The highest milestone wins and doesn't matter how many commits you made with the same milestone trailer information or the order in which the commits were made. Here's another example:

....

First commit.

Milestone: patch

Second commit.

Milestone: patch

Third commit

Milestone: patch ....

Given the above, the resulting version would be: 1.0.1. This is because the highest milestone was a patch. Here's a final example:

....

First commit.

Milestone: major

Second commit.

Milestone: minor

Third commit

Milestone: patch ....

Given the above, the resulting version would be: 2.0.0. This is because the highest milestone was a major milestone.

==== Templates

Build template functionality is powered by {hanami_views_link} which means you can customize the HTML structure, CSS style, and more. The quickest way to get started is to copy the templates folder structure -- included with this gem -- to your preferred {runcom_link} configuration. For example, this gem's template structure is:

.... lib/milestoner/templates ├── layouts │ ├── page.adoc.erb │ ├── page.html.erb │ ├── page.md.erb │ └── page.stream.erb ├── milestones │ ├── _avatar.html.erb │ ├── _commit.adoc.erb │ ├── _commit.html.erb │ ├── _commit.md.erb │ ├── _commit.stream.erb │ ├── _icon.html.erb │ ├── _profile.html.erb │ ├── show.adoc.erb │ ├── show.html.erb │ ├── show.md.erb │ └── show.stream.erb └── public └── page.css.erb ....

This means you could, for example, copy all of this gem's templates to your own {runcom_link} configuration to customize how you like. Example:

[source,bash]

cp -r <milestoner_gem_root>/lib/milestoner/templates $HOME/.config/milestoner/templates

Milestoner searches your {runcom_link} configuration first and, if templates are detected, will be used instead. Otherwise, Milestoner falls back to it's own templates. Once {runcom_link} has calculated all possible template locations, {hanami_views_link} handle the final loading and evaluation of your templates.

==== Web Format

Of all the build formats supported, the web format is the most powerful, feature rich, and is why it's the default format. The following showcases some of the information rendered in this format based on commit activity.

Wit Basic Git Commit

image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-overview.png[Usage,width=1228,height=808,role=focal_point]

With Git Commit Notes and Trailers

image:https://alchemists.io/images/projects/milestoner/screenshots/web_format-notes_and_collaborators.png[Usage,width=1228,height=808,role=focal_point]

Each milestone is meant to provide you with the right amount of statistical information you can make informed decisions.

== Security

To securely sign your {git_link} 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_link} 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_link} 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].