milestoner 17.0.0 → 17.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c3705bded27a22253cc186854ca6f39a73aa441fa5ff065ea76c23250e0e5d
-  data.tar.gz: 187d16fc088ae2f84774f77ba3bfb35b3875481f127c73dd1ac66b082332a814
+  metadata.gz: 617cfbe964559f51bcb4adf23bba33b72c4dd30c59ca5a0c4c7de47d0f15c1a6
+  data.tar.gz: c15cb3387ee97ce734c7fd33c686586e35766ded1fc52541db791a1ecf52086c
 SHA512:
-  metadata.gz: cd2db5bbb280f82e2cc40530e183cc2e822d8df0e5ce3260893606a25b3ca5ba37cc5a016d11ecc26d0f2e306eb0f1f56bc6996cfdc990719dc4ddcca3b7fb22
-  data.tar.gz: 99d0e185f7861d29bfb701b229a248298a361848bbabbc4c6e43adb96376c3051370eb8546887a134e18eaefa25573455edede1f9d0c0bf519660cea8a2f7740
+  metadata.gz: dd84afec04ee0568952de234de6901e79239c4be77b694861743e994b4ad44f29face960ed74202defb074cae4946ab025982250b3c213ad85e89c582f2527f9
+  data.tar.gz: 6354a71fe755ec98c0f089941252fb6191a411ad31df97754c45ddd13bc3cafcf4bd180f4d56d10af15856692e00199903ad22c96c87a89a943bfe62834985f0

data/README.adoc

@@ -2,58 +2,78 @@
 :toclevels: 5
 :figure-caption!:
 
-:asciidoc_link: link:https://asciidoctor.org/docs/what-is-asciidoc[ASCII Doc]
+: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]
+: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_views_link: link:https://alchemists.io/articles/hanami_views[Hanami Views]
+:hanami_link: link:https://hanamirb.org[Hanami]
+:hanami_views_link: link:https://alchemists.io/articles/hanami_views[Hanami View]
+: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 Command Line Interface (CLI) for automating software deployments complete with feature rich release notes that celebrate the team members who worked on the version release. This includes the automation of Git repository tags (milestones) using link:https://semver.org[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:
+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.
 
-- link:https://alchemists.io/projects/git-lint[Git Lint] - Ensures your commit messages are of
-  high quality for release note purposes.
-- link:https://alchemists.io/projects/rubysmith[Rubysmith] - Automates the publishing of new or existing Ruby project versions.
-- link:https://alchemists.io/projects/gemsmith[Gemsmith] - Automates the publishing of new or existing Ruby gem versions.
+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
 
-*Web Format* (i.e. `milestoner build --format web`)
+*ASCII Doc Format* (i.e. `milestoner build --format ascii_doc`)
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-collapsed.png[Usage,width=1011,height=345,role=focal_point]
+image:https://alchemists.io/images/projects/milestoner/screenshots/build-ascii_doc.png[Usage,width=787,height=257,role=focal_point]
 
-image:https://alchemists.io/images/projects/milestoner/screenshots/build-web-expanded.png[Usage,width=1005,height=643,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=245,role=focal_point]
+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 link:https://alchemists.io/projects/versionaire[Versionaire] for
-  link:https://semver.org[Semantic Versioning].
+* Uses {versionaire_link} for {strict_semantic_versioning_link}. Example:
 ** Format: `+<major>.<minor>.<patch>+`.
 ** Example: `0.0.0`.
-* Ensures Git commits since last tag (or initialization of repository) are included in the release notes.
-* Ensures Git 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):
+* 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 commit messages are alphabetically sorted for release note categorization and readability.
-* Provides automatic versioning based on last Git tag and current Git commit trailers. See {git_commit_anatomy_link} for details.
+* 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} templates.
 
 == Requirements
 
@@ -123,6 +143,9 @@ commit:
   domain: https://github.com
   format: asciidoc
   uri: "%<domain>s/%<owner>s/%<name>s/commit/%<id>s"
+generator:
+  label:
+  uri:
 profile:
   domain: https://github.com
   uri: "%<domain>s/%<id>s"
@@ -146,46 +169,53 @@ tracker:
 The above can be customized as follows:
 
 * `avatar`: Manages team member avatar information.
-** `domain`: The domain of your team member avatars.
-** `uri`: The URI format for linking to avatars as formatted using {string_formats_link}. The `id` is dynamically calculated via the `external_id` of the user stored in the {lode_link} cache.
+** `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`: The build output format. Multiple formats are supported.
-** `layout`: The layout used by {hanami_views_link} when building release notes.
-** `root`: The output location. This can be a relative or absolute path.
+** `format`: Required. The build output format. Multiple formats are supported. Default: web.
+** `layout`: Required. The layout used by the {hanami_views_link} gem 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`: 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`: The emoji associated with the label for output purposes. _Only used by the stream build format_.
-*** `label`: 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.
-** `domain`: The Git repository domain for all commits.
-** `format`: Defines the default format used for rendering commit messages unless specified in the commit trailer metadata which takes higher precedence. Defaults to {asciidoc_link} but {markdown_link} is also supported.
-** `uri`: The URI format for linking to commits as formatted using {string_formats_link}. The `id` is dynamically calculated via the commit SHA of each commit analyzed at runtime.
+** `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.
 * `profile`: Manages team member profile information.
-** `domain`: The domain of your Git repository.
-** `uri`: 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.
+** `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`: Optional. The project author. Dynamically calculated by the {etcher_link} gem in the following order: Git configuration user name or this value.
-** `description`: Optional. The project description. Dynamically calculated by the {etcher_link} gem in the following order: {gem_specification_link} summary, {cff_link} abstract, or this value.
-** `generator`: Optional. The project generator (i.e. this gem).
-** `label`: Optional. The project label. Dynamically calculated by the {etcher_link} gem in the following order: {gem_specification_link} metadata label, {cff_link} title, or this value.
-** `name`: Optional. The project name. Dynamically calculated by the {etcher_link} gem in the following order: {gem_specification_link} name or this value.
-** `owner`: Required. The project owner. This would be your source code organization or user handle. This is used when formatting URL information (mentioned above).
-** `uri`: Optional. The project URI. Dynamically calculated by the {etcher_link} gem in the following order: {gem_specification_link} homepage or this value.
-** `version`: Optional. The project version. Dynamically calculated based on the last Git tag of your project and Git `Milestone` commit trailer metadata. Otherwise, defaults to: `0.0.0`. For more on this see, the _Automatic Versioning_ section below.
+** `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`: The domain of your code review service.
-** `uri`: The URI format for linking to code reviews as formatted using {string_formats_link}. 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 commit trailers.
-* `tracker`: Allows you to customize the issue tracker service you are using.
-** `domain`: The domain of your issue tracker service.
-** `uri`: The URI format for linking to issues as formatted using {string_formats_link}. The `id` is dynamically calculated via the commit `Issue` trailer as linted by {git_lint_link}.
+** `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 currrent configuration looks like you can jump into your applications IRB console and inspect `Milestoner::Container[:configuration]` to see full details.
+💡 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
 
-Milestoner can be configured via the command line using: `milestoner config`. Using this command will allow 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.
+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:
@@ -229,11 +259,13 @@ Once team member information is stored in your cache, you'll be able to build re
 
 === Build
 
-The build command allows you to quickly build release notes for checking the current status of your project or for deployment automation. 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:
+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 html
+milestoner build --format web
 # 🟢 Building milestone...
 # 🟢 Milestone built: /Users/bkuhlmann/Engineering/OSS/milestoner/tmp/milestone
 ----
@@ -244,7 +276,7 @@ Check out the help documentation (i.e. `milestoner build --help`) for addition u
 
 ==== Automatic Versioning
 
-As mentioned earlier, the calculation of version information happens automatically for you based on your last Git tag and any Git 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:
+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]
 ----
@@ -262,7 +294,7 @@ milestoner build --format stream
 milestoner build --format stream --version 1.2.3
 ----
 
-By default, automatic versioning is based on your last known Git tag and the version is bumped based on Git 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 commit trailer with a value of: `patch`, `minor`, or `major`. Here's an example assuming you have published Version 1.0.0:
+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.
@@ -305,20 +337,26 @@ Given the above, the resulting version would be: 2.0.0. This is because the high
 
 ==== 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:
+Build template functionality is powered by the {hanami_views_link} gem 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
@@ -333,9 +371,23 @@ cp -r <milestoner_gem_root>/lib/milestoner/templates $HOME/.config/milestoner/te
 
 Milestoner searches your {runcom_link} configuration first and, if templates are detected, will be used instead. Otherwise, Milestoner will fall back to it's own templates. Once {runcom_link} has calculated all possible template locations, {hanami_views_link} handles 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 tags, install and configure https://www.gnupg.org[GPG]:
+To securely sign your {git_link} tags, install and configure https://www.gnupg.org[GPG]:
 
 [source,bash]
 ----
@@ -358,8 +410,7 @@ 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:
+Add your key to your global (or local) {git_link} configuration and ensure GPG signing for your tag is enabled. Example:
 
 ....
 [tag]
@@ -369,10 +420,8 @@ enabled. Example:
 ....
 
 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
-link:https://gnupg.org/documentation/manuals/gnupg/Invoking-GPG_002dAGENT.html#Invoking-GPG_002dAGENT[GPG
-Agent] in the background (highly recommend).
+{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
 

data/lib/milestoner/builders/ascii_doc.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Milestoner
+  module Builders
+    # Builds Markdown page output.
+    class ASCIIDoc
+      include Milestoner::Import[:input]
+
+      using Refinements::Pathname
+
+      def initialize(view: Views::Milestones::Show.new, enricher: Commits::Enricher.new, **)
+        @view = view
+        @enricher = enricher
+        super(**)
+      end
+
+      def call at: Time.now.utc
+        input.build_root.join("index.adoc").make_ancestors.tap { |path| write path, at }
+      end
+
+      private
+
+      attr_reader :view, :enricher
+
+      def write path, at
+        enricher.call.fmap do |commits|
+          path.write view.call commits:, at:, layout: input.build_layout, format: :adoc
+        end
+      end
+    end
+  end
+end

data/lib/milestoner/builders/container.rb

@@ -8,6 +8,8 @@ module Milestoner
     module Container
       extend Dry::Container::Mixin
 
+      register(:ascii_doc, memoize: true) { ASCIIDoc.new }
+      register(:markdown, memoize: true) { Markdown.new }
       register(:stream, memoize: true) { Stream.new }
       register(:web, memoize: true) { Web.new }
     end

data/lib/milestoner/builders/markdown.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Milestoner
+  module Builders
+    # Builds Markdown page output.
+    class Markdown
+      include Milestoner::Import[:input]
+
+      using Refinements::Pathname
+
+      def initialize(view: Views::Milestones::Show.new, enricher: Commits::Enricher.new, **)
+        @view = view
+        @enricher = enricher
+        super(**)
+      end
+
+      def call at: Time.now.utc
+        input.build_root.join("index.md").make_ancestors.tap { |path| write path, at }
+      end
+
+      private
+
+      attr_reader :view, :enricher
+
+      def write path, at
+        enricher.call.fmap do |commits|
+          path.write view.call commits:, at:, layout: input.build_layout, format: :md
+        end
+      end
+    end
+  end
+end

data/lib/milestoner/cli/actions/build/format.rb

@@ -12,7 +12,7 @@ module Milestoner
 
           description "Set output format."
 
-          on %w[-f --format], argument: "[KIND]", allow: %w[stream web]
+          on %w[-f --format], argument: "[KIND]", allow: %w[ascii_doc markdown stream web]
 
           default { Container[:configuration].build_format }
 

data/lib/milestoner/cli/actions/build/label.rb

@@ -16,7 +16,7 @@ module Milestoner
 
           on %w[-l --label], argument: "[TEXT]"
 
-          default { Spek::Loader.call("#{Pathname.pwd.basename}.gemspec").label }
+          default { Container[:configuration].project_label }
 
           def call(label = nil) = input.project_label = label || default
         end

data/lib/milestoner/cli/actions/build/version.rb

@@ -21,7 +21,7 @@ module Milestoner
 
           on %w[-v --version], argument: "[VERSION]"
 
-          default { Commits::Versioner.new.call }
+          default { Container[:configuration].project_version }
 
           def call(version = nil) = input.project_version = Version(version || default)
         end

data/lib/milestoner/cli/actions/cache/delete.rb

@@ -23,10 +23,7 @@ module Milestoner
 
           def success(user) = logger.info { "Deleted: #{user.name.inspect}." }
 
-          def failure message
-            logger.error { message }
-            kernel.abort
-          end
+          def failure(message) = logger.abort message
         end
       end
     end

data/lib/milestoner/cli/actions/cache/find.rb

@@ -23,10 +23,7 @@ module Milestoner
 
           def success(user) = kernel.puts user.to_h.values.join(", ")
 
-          def failure message
-            logger.error { message }
-            kernel.abort
-          end
+          def failure(message) = logger.abort message
         end
       end
     end

data/lib/milestoner/cli/actions/publish.rb

@@ -20,7 +20,7 @@ module Milestoner
 
         on %w[-p --publish], argument: "[VERSION]"
 
-        default { Commits::Versioner.new.call }
+        default { Container[:configuration].project_version }
 
         def initialize(publisher: Tags::Publisher.new, **)
           super(**)

data/lib/milestoner/cli/commands/build.rb

@@ -9,7 +9,7 @@ module Milestoner
       # Handles the building of milestone output.
       class Build < Sod::Command
         include Import[:input, :logger, :kernel]
-        include Builders::Import[:stream, :web]
+        include Builders::Import[:ascii_doc, :markdown, :stream, :web]
 
         using Refinements::Pathname
 
@@ -23,15 +23,18 @@ module Milestoner
         on Actions::Build::Format
         on Actions::Build::Root
 
+        # :reek:TooManyStatements
         def call
           log_info "Building milestone..."
 
           format = input.build_format
 
           case format
+            when "ascii_doc" then build_ascii_doc
+            when "markdown" then build_markdown
             when "stream" then build_stream
             when "web" then build_web
-            else log_error "Invalid build format: #{format}."
+            else logger.abort "Invalid build format: #{format}."
           end
         end
 
@@ -39,6 +42,10 @@ module Milestoner
 
         attr_reader :view, :enricher
 
+        def build_ascii_doc = log_info("Milestone built: #{ascii_doc.call}.")
+
+        def build_markdown = log_info("Milestone built: #{markdown.call}.")
+
         def build_stream
           kernel.puts
           stream.call
@@ -47,8 +54,6 @@ module Milestoner
         def build_web = log_info "Milestone built: #{web.call}."
 
         def log_info(message) = logger.info { message }
-
-        def log_error(message) = logger.error { message }
       end
     end
   end

data/lib/milestoner/commits/enricher.rb

@@ -27,7 +27,6 @@ module Milestoner
         @categorizer = categorizer
         @model = model
         super(**)
-        @commands = %i[author body collaborators format issue milestone notes review signers uri]
       end
 
       def call
@@ -38,12 +37,12 @@ module Milestoner
 
       private
 
-      attr_reader :categorizer, :model, :commands
+      attr_reader :categorizer, :model
 
       def record_for(commit) = model.for(commit, **build_attributes(commit))
 
       def build_attributes commit
-        commands.each.with_object({}) do |command, attributes|
+        infused_keys.each.with_object({}) do |command, attributes|
           attributes[command] = __send__(command).call commit
         end
       end

data/lib/milestoner/configuration/contract.rb

@@ -23,15 +23,16 @@ module Milestoner
       required(:commit_domain).filled :string
       required(:commit_format).filled :string
       required(:commit_uri).filled :string
+      required(:generator_label).filled :string
+      required(:generator_uri).filled :string
       required(:profile_domain).filled :string
       required(:profile_uri).filled :string
       required(:project_author).filled :string
-      optional(:project_description).filled :string
-      required(:project_generator).filled :string
+      optional(:project_description).maybe :string
       optional(:project_label).filled :string
       required(:project_name).filled :string
       optional(:project_owner).filled :string
-      optional(:project_uri).filled :string
+      optional(:project_uri).maybe :string
       required(:project_version).filled Etcher::Types::Version
       required(:review_domain).filled :string
       required(:review_uri).filled :string

data/lib/milestoner/configuration/model.rb

@@ -13,6 +13,8 @@ module Milestoner
                        :commit_domain,
                        :commit_format,
                        :commit_uri,
+                       :generator_label,
+                       :generator_uri,
                        :profile_domain,
                        :profile_uri,
                        :project_author,

data/lib/milestoner/configuration/transformers/build/template_paths.rb

@@ -20,10 +20,7 @@ module Milestoner
             @xdg_config = xdg_config
           end
 
-          def call content
-            content[key] = xdg_config.all.append default
-            Success content
-          end
+          def call(content) = Success content.merge!(key => xdg_config.all.append(default))
 
           private
 

data/lib/milestoner/configuration/transformers/citations/description.rb

@@ -3,6 +3,7 @@
 require "cff"
 require "dry/monads"
 require "pathname"
+require "refinements/hash"
 
 module Milestoner
   module Configuration
@@ -12,6 +13,8 @@ module Milestoner
         class Description
           include Dry::Monads[:result]
 
+          using Refinements::Hash
+
           def initialize key = :project_description,
                          path: Pathname.pwd.join("CITATION.cff"),
                          citation: CFF::File
@@ -20,16 +23,15 @@ module Milestoner
             @citation = citation
           end
 
-          def call(content) = Success process(content)
+          def call content
+            content.fetch_value(key) { citation.open(path).abstract }
+                   .then { |value| value unless String(value).empty? }
+                   .then { |value| Success content.merge!(key => value) }
+          end
 
           private
 
           attr_reader :key, :path, :citation
-
-          def process content
-            content.fetch(key) { citation.open(path).abstract }
-                   .then { |value| String(value).empty? ? content : content.merge!(key => value) }
-          end
         end
       end
     end