releasehx 0.1.2 → 0.2.0

data/build/docs/release-procedure.adoc

@@ -0,0 +1,365 @@
+= ReleaseHx Release Procedure
+
+This document outlines the step-by-step procedure for releasing a new version of ReleaseHx.
+
+It covers all stages from pre-release checks to post-release verification.
+
+
+[[prerequisites]]
+== Prerequisites
+
+- [ ] All changes merged to `release/0.x` branch
+- [ ] Version numbers updated in README.adoc attributes (`:this_prod_vrsn_major:` through `:next_prod_vrsn_majmin:`)
+- [ ] Release notes prepared in `docs/release/0.x.y.adoc`
+- [ ] Clean working tree on `release/0.x`
+- [ ] RubyGems credentials configured (`~/.gem/credentials`)
+- [ ] Docker Hub credentials configured (`docker login`)
+
+
+[[release-stages]]
+== Release Stages
+
+[[stage-pre-flight-checks]]
+=== Stage {counter:stage}: Pre-flight Checks
+
+Verify CI/CD Setup::
++
+[source,bash]
+----
+# Check workflows exist
+ls .github/workflows/
+# Should see: ci-cd.yml, gh-pages.yml, docs-qa.yml
+----
+
+Check Current State::
++
+[source,bash]
+----
+# Verify branch and clean status
+git status
+# Should be on release/0.x with clean working tree
+----
+
+Run Test Suite::
++
+[source,bash]
+----
+bundle exec rake rspec
+# All tests must pass
+----
+
+Confirm demo builds in releasehx-demo repo::
++
+[source,bash]
+----
+cd ../releasehx-demo
+./dev-install.sh
+bundle exec rake test:yaml
+bundle exec rake test:cli
+bundle exec rake test:readme
+bundle exec rake test:dynamic
+bundle exec rake test:content
+----
+
+Check demo test results::
++
+[source,bash]
+----
+# View test output directories
+ls -lh __tests/
+# Should contain: cli/, readme/, dynamic/, validation/
+
+# Check for errors in output
+grep -i error __tests/*/*.log 2>/dev/null || echo "No errors found"
+
+# Spot-check generated files
+ls -lh __output/drafts/
+ls -lh __output/publish/
+----
+
+Demo Repo Release Readiness::
+
+- [ ] YAML validation passes
+(`yaml_test`)
+- [ ] CLI workflows pass (`cli_test`) 
+- [ ] README testable commands pass (`readme_test`)
+- [ ] Dynamic test matrix passes (`dynamic_test`)
+- [ ] Content validation passes (`validate_content`)
+- [ ] Test output
+directories contain no errors
+- [ ] Generated files present in
+__output/
+
+Test Docker Build::
++
+[source,bash]
+----
+bundle exec rake build:image
+# Note: This creates/updates the buildx builder and tests the build
+# May need to recreate builder after Docker updates: docker buildx rm releasehx-builder
+----
+
+Verify Version Numbers::
++
+[source,bash]
+----
+# Check version in README.adoc
+grep ":this_prod_vrsn" README.adoc
+# Verify lib/releasehx/version.rb reads from README attributes
+grep "VERSION" lib/releasehx/version.rb
+----
+
+Verify Gemfile::
++
+[source,bash]
+----
+# Ensure no local path dependencies
+grep -E "path:|git:" Gemfile
+# Should be empty
+----
+
+Confirm Release Notes::
++
+[source,bash]
+----
+# Verify release notes file exists
+ls -lh docs/release/0.x.y.adoc
+----
+
+[[stage-build-artifacts]]
+=== Stage {counter:stage}: Build Artifacts
+
+Build Gem Package::
++
+[source,bash]
+----
+bundle exec rake build:gem
+----
+
+Verify Gem Package::
++
+[source,bash]
+----
+ls -lh pkg/releasehx-*.gem
+# Confirm version number is correct
+----
+
+[[stage-create-pull-request]]
+=== Stage {counter:stage}: Create Pull Request
+
+Push Release Branch::
++
+[source,bash]
+----
+git push origin release/0.x
+----
+
+Create Pull Request::
+* Via GitHub UI:
+https://github.com/DocOps/releasehx/compare/main…release/0.x
+* Title:
+Release 0.x.y
+* Body: (leave empty); wait for CI tests to pass.
+
+Merge Strategy::
+Use "`Create a merge commit`" (NOT squash or rebase).
+This preserves commit history and allows future PRs from the same
+branch
+
+[[stage-tag-release]]
+=== Stage {counter:stage}: Tag Release
+
+Update Local Main Branch::
++
+[source,bash]
+----
+git checkout main
+git pull origin main
+----
+
+Create and Push Tag::
++
+[source,bash]
+----
+git tag -a v0.x.y -m "Release 0.x.y"
+git push origin v0.x.y
+----
+
+NOTE: GitHub Pages workflow will auto-deploy docs when tag is pushed.
+
+[[stage-sync-release]]
+=== Stage {counter:stage}: Sync Release Branch (Optional but Recommended)
+
+Cherry-pick Any Post-Merge Fixes::
+If you made any fixes to release notes or docs on main after the merge:
++
+[source,bash]
+----
+git checkout release/0.x
+git cherry-pick <commit-sha>
+git push origin release/0.x
+----
+
+[[stage-publish-gem-to-rubygems]]
+=== Stage {counter:stage}: Publish Gem to RubyGems
+
+[source,bash]
+----
+gem push pkg/releasehx-0.x.y.gem
+# Enter OTP code from authenticator when prompted
+----
+
+Verify Publication::
++
+[source,bash]
+----
+# Check on RubyGems.org
+open https://rubygems.org/gems/releasehx
+----
+
+[[stage-publish-docker-image]]
+=== Stage {counter:stage}: Publish Docker Image
+
+Build and Load Image::
++
+[source,bash]
+----
+docker buildx build --platform linux/amd64 \
+  --build-arg RELEASEHX_VERSION=0.x.y \
+  -t docopslab/releasehx:latest \
+  -t docopslab/releasehx:0.x.y \
+  --load \
+  .
+----
+
+Push Images::
++
+[source,bash]
+----
+docker push docopslab/releasehx:0.x.y
+docker push docopslab/releasehx:latest
+----
+
+Verify Publication::
++
+[source,bash]
+----
+# Check on Docker Hub
+open https://hub.docker.com/r/docopslab/releasehx
+----
+
+[[stage-publish-issuer-rhx]]
+=== Stage {counter:stage}: Publish issuer-rhx Docker Image
+
+Follow the Release Process documented in the https://github.com/DocOps/issuer-rhx[issuer-rhx] repo's `README.adoc`.
+
+
+[[stage-create-github-release]]
+=== Stage {counter:stage}: Create GitHub Release
+
+Via GitHub UI (recommended)::
+. Go to:
+https://github.com/DocOps/releasehx/releases/new
+. Select tag: v0.x.y
+. Title: ReleaseHx 0.x.y
+. Description:
+See release notes at `https://releasehx.docopslab.org/docs/releases/`
+. Upload: `pkg/releasehx-0.x.y.gem`
+. Click "`Publish release`"
+
+Via CLI (if permissions allow)::
++
+[source,bash]
+----
+gh release create v0.x.y pkg/releasehx-0.x.y.gem \
+  --title "ReleaseHx 0.x.y" \
+  --notes "See release notes at https://releasehx.docopslab.org/docs/releases/"
+----
+
+[[stage-release-verification]]
+=== Stage {counter:stage}: Post-Release Verification
+
+Test Gem Installation::
++
+[source,bash]
+----
+gem install releasehx --version 0.x.y
+rhx --version
+# Should show: 0.x.y
+----
+
+Test Docker Image::
++
+[source,bash]
+----
+docker pull docopslab/releasehx:0.x.y
+docker run --rm docopslab/releasehx:0.x.y rhx --version
+# Should show: 0.x.y
+----
+
+Verify Documentation::
++
+[source,bash]
+----
+# Check that docs are live
+open https://releasehx.docopslab.org/docs/releases/
+# Should show 0.x.y release notes
+----
+
+[[stage-post-release-cleanup-optional]]
+=== Stage {counter:stage}: Post-Release Cleanup (Optional)
+
+Update Version for Next Release::
+Edit `README.adoc` to increment patch version; commit on `release/0.x` branch
+
+Notify Stakeholders::
+Post announcement in relevant channels; update downstream projects
+
+
+[[troubleshooting]]
+== Troubleshooting
+
+[[docker-buildkit-issues]]
+=== Docker BuildKit Issues
+
+If you encounter TLS certificate errors with buildx:
+
+[source,bash]
+----
+# Remove stale builder
+docker buildx rm releasehx-builder
+
+# Recreate builder (Rakefile will do this automatically)
+bundle exec rake build:image
+----
+
+[[mfa-otp-issues]]
+=== MFA/OTP Issues with RubyGems
+
+* Get fresh OTP code from authenticator app
+* Code expires quickly; have app ready before running `gem push`
+
+[[github-cli-permission-issues]]
+=== GitHub CLI Permission Issues
+
+If `gh` CLI lacks permissions::
+
+* Use GitHub web UI for creating PRs and
+Releases
+* Upload gem file manually in Release creation form
+
+
+[[branch-strategy]]
+== Branch Strategy
+
+Long-lived Branch (`release/0.x`)::
+* Used for all 0.x.y patch releases
+* PR to main for each release
+* Merge commits preserve history
+* Continue development on same branch
+
+Tagging::
+Tags created on `main` branch after merge
+
+Documentation::
+Auto-deploys from `main` via GitHub Actions

data/build/docs/release-procedure.html

@@ -0,0 +1,87 @@
+<h1>ReleaseHx Release Procedure</h1>
+
+<section id="preamble" aria-label="Preamble"><p>This document outlines the step-by-step procedure for releasing a new version of ReleaseHx.</p>
+<p>It covers all stages from pre-release checks to post-release verification.</p></section>
+<section class="doc-section level-1"><h2 id="prerequisites">Prerequisites</h2><div class="ulist"><ul class="task-list"><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> All changes merged to <code>release/0.x</code> branch</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Version numbers updated in README.adoc attributes (<code>:this_prod_vrsn_major:</code> through <code>:next_prod_vrsn_majmin:</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Release notes prepared in <code>docs/release/0.x.y.adoc</code></li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Clean working tree on <code>release/0.x</code></li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> RubyGems credentials configured (<code>~/.gem/credentials</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Docker Hub credentials configured (<code>docker login</code>)</li></ul></div></section>
+<section class="doc-section level-1"><h2 id="release-stages">Release Stages</h2><section class="doc-section level-2"><h3 id="stage-pre-flight-checks">Stage 1: Pre-flight Checks</h3><div class="dlist"><dl><dt>Verify CI/CD Setup</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Check workflows exist
+ls .github/workflows/
+# Should see: ci-cd.yml, gh-pages.yml, docs-qa.yml</code></pre></div></dd><dt>Check Current State</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Verify branch and clean status
+git status
+# Should be on release/0.x with clean working tree</code></pre></div></dd><dt>Run Test Suite</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">bundle exec rake rspec
+# All tests must pass</code></pre></div></dd><dt>Confirm demo builds in releasehx-demo repo</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">cd ../releasehx-demo
+./dev-install.sh
+bundle exec rake test:yaml
+bundle exec rake test:cli
+bundle exec rake test:readme
+bundle exec rake test:dynamic
+bundle exec rake test:content</code></pre></div></dd><dt>Check demo test results</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># View test output directories
+ls -lh __tests/
+# Should contain: cli/, readme/, dynamic/, validation/
+
+# Check for errors in output
+grep -i error __tests/*/*.log 2&gt;/dev/null || echo "No errors found"
+
+# Spot-check generated files
+ls -lh __output/drafts/
+ls -lh __output/publish/</code></pre></div></dd><dt>Demo Repo Release Readiness</dt><dd><ul class="task-list"><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> YAML validation passes
+(<code>yaml_test</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> CLI workflows pass (<code>cli_test</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> README testable commands pass (<code>readme_test</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Dynamic test matrix passes (<code>dynamic_test</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Content validation passes (<code>validate_content</code>)</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Test output
+directories contain no errors</li><li class="task-list-item"><input class="task-list-item-checkbox" type="checkbox" disabled> Generated files present in
+__output/</li></ul></dd><dt>Test Docker Build</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">bundle exec rake build:image
+# Note: This creates/updates the buildx builder and tests the build
+# May need to recreate builder after Docker updates: docker buildx rm releasehx-builder</code></pre></div></dd><dt>Verify Version Numbers</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Check version in README.adoc
+grep ":this_prod_vrsn" README.adoc
+# Verify lib/releasehx/version.rb reads from README attributes
+grep "VERSION" lib/releasehx/version.rb</code></pre></div></dd><dt>Verify Gemfile</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Ensure no local path dependencies
+grep -E "path:|git:" Gemfile
+# Should be empty</code></pre></div></dd><dt>Confirm Release Notes</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Verify release notes file exists
+ls -lh docs/release/0.x.y.adoc</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-build-artifacts">Stage 2: Build Artifacts</h3><div class="dlist"><dl><dt>Build Gem Package</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">bundle exec rake build:gem</code></pre></div></dd><dt>Verify Gem Package</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">ls -lh pkg/releasehx-*.gem
+# Confirm version number is correct</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-create-pull-request">Stage 3: Create Pull Request</h3><div class="dlist"><dl><dt>Push Release Branch</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">git push origin release/0.x</code></pre></div></dd><dt>Create Pull Request</dt><dd><ul><li>Via GitHub UI:
+<a class="bare" href="https://github.com/DocOps/releasehx/compare/main…release/0.x">https://github.com/DocOps/releasehx/compare/main…release/0.x</a></li><li>Title:
+Release 0.x.y</li><li>Body: (leave empty); wait for CI tests to pass.</li></ul></dd><dt>Merge Strategy</dt><dd>Use &#x201c;Create a merge commit&#x201d; (NOT squash or rebase).
+This preserves commit history and allows future PRs from the same
+branch</dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-tag-release">Stage 4: Tag Release</h3><div class="dlist"><dl><dt>Update Local Main Branch</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">git checkout main
+git pull origin main</code></pre></div></dd><dt>Create and Push Tag</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">git tag -a v0.x.y -m "Release 0.x.y"
+git push origin v0.x.y</code></pre></div></dd></dl></div>
+<aside class="admonition-block note" role="note"><h6 class="block-title label-only"><span class="title-label">Note: </span></h6><p>GitHub Pages workflow will auto-deploy docs when tag is pushed.</p></aside></section>
+<section class="doc-section level-2"><h3 id="stage-sync-release">Stage 5: Sync Release Branch (Optional but Recommended)</h3><div class="dlist"><dl><dt>Cherry-pick Any Post-Merge Fixes</dt><dd><p>If you made any fixes to release notes or docs on main after the merge:</p><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">git checkout release/0.x
+git cherry-pick &lt;commit-sha&gt;
+git push origin release/0.x</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-publish-gem-to-rubygems">Stage 6: Publish Gem to RubyGems</h3><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">gem push pkg/releasehx-0.x.y.gem
+# Enter OTP code from authenticator when prompted</code></pre></div>
+<div class="dlist"><dl><dt>Verify Publication</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Check on RubyGems.org
+open https://rubygems.org/gems/releasehx</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-publish-docker-image">Stage 7: Publish Docker Image</h3><div class="dlist"><dl><dt>Build and Load Image</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">docker buildx build --platform linux/amd64 \
+  --build-arg RELEASEHX_VERSION=0.x.y \
+  -t docopslab/releasehx:latest \
+  -t docopslab/releasehx:0.x.y \
+  --load \
+  .</code></pre></div></dd><dt>Push Images</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">docker push docopslab/releasehx:0.x.y
+docker push docopslab/releasehx:latest</code></pre></div></dd><dt>Verify Publication</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Check on Docker Hub
+open https://hub.docker.com/r/docopslab/releasehx</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-publish-issuer-rhx">Stage 8: Publish issuer-rhx Docker Image</h3><p>Follow the Release Process documented in the <a href="https://github.com/DocOps/issuer-rhx">issuer-rhx</a> repo&#8217;s <code>README.adoc</code>.</p></section>
+<section class="doc-section level-2"><h3 id="stage-create-github-release">Stage 9: Create GitHub Release</h3><div class="dlist"><dl><dt>Via GitHub UI (recommended)</dt><dd><ol class="arabic"><li>Go to:
+<a class="bare" href="https://github.com/DocOps/releasehx/releases/new">https://github.com/DocOps/releasehx/releases/new</a></li><li>Select tag: v0.x.y</li><li>Title: ReleaseHx 0.x.y</li><li>Description:
+See release notes at <code><a class="bare" href="https://releasehx.docopslab.org/docs/releases/">https://releasehx.docopslab.org/docs/releases/</a></code></li><li>Upload: <code>pkg/releasehx-0.x.y.gem</code></li><li>Click &#x201c;Publish release&#x201d;</li></ol></dd><dt>Via CLI (if permissions allow)</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">gh release create v0.x.y pkg/releasehx-0.x.y.gem \
+  --title "ReleaseHx 0.x.y" \
+  --notes "See release notes at https://releasehx.docopslab.org/docs/releases/"</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-release-verification">Stage 10: Post-Release Verification</h3><div class="dlist"><dl><dt>Test Gem Installation</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">gem install releasehx --version 0.x.y
+rhx --version
+# Should show: 0.x.y</code></pre></div></dd><dt>Test Docker Image</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash">docker pull docopslab/releasehx:0.x.y
+docker run --rm docopslab/releasehx:0.x.y rhx --version
+# Should show: 0.x.y</code></pre></div></dd><dt>Verify Documentation</dt><dd><div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Check that docs are live
+open https://releasehx.docopslab.org/docs/releases/
+# Should show 0.x.y release notes</code></pre></div></dd></dl></div></section>
+<section class="doc-section level-2"><h3 id="stage-post-release-cleanup-optional">Stage 11: Post-Release Cleanup (Optional)</h3><div class="dlist"><dl><dt>Update Version for Next Release</dt><dd>Edit <code>README.adoc</code> to increment patch version; commit on <code>release/0.x</code> branch</dd><dt>Notify Stakeholders</dt><dd>Post announcement in relevant channels; update downstream projects</dd></dl></div></section></section>
+<section class="doc-section level-1"><h2 id="troubleshooting">Troubleshooting</h2><section class="doc-section level-2"><h3 id="docker-buildkit-issues">Docker BuildKit Issues</h3><p>If you encounter TLS certificate errors with buildx:</p>
+<div class="listing-block"><pre class="highlight"><code class="language-bash" data-lang="bash"># Remove stale builder
+docker buildx rm releasehx-builder
+
+# Recreate builder (Rakefile will do this automatically)
+bundle exec rake build:image</code></pre></div></section>
+<section class="doc-section level-2"><h3 id="mfa-otp-issues">MFA/OTP Issues with RubyGems</h3><div class="ulist"><ul><li>Get fresh OTP code from authenticator app</li><li>Code expires quickly; have app ready before running <code>gem push</code></li></ul></div></section>
+<section class="doc-section level-2"><h3 id="github-cli-permission-issues">GitHub CLI Permission Issues</h3><div class="dlist"><dl><dt>If <code>gh</code> CLI lacks permissions</dt><dd><ul><li>Use GitHub web UI for creating PRs and
+Releases</li><li>Upload gem file manually in Release creation form</li></ul></dd></dl></div></section></section>
+<section class="doc-section level-1"><h2 id="branch-strategy">Branch Strategy</h2><div class="dlist"><dl><dt>Long-lived Branch (<code>release/0.x</code>)</dt><dd><ul><li>Used for all 0.x.y patch releases</li><li>PR to main for each release</li><li>Merge commits preserve history</li><li>Continue development on same branch</li></ul></dd><dt>Tagging</dt><dd>Tags created on <code>main</code> branch after merge</dd><dt>Documentation</dt><dd>Auto-deploys from <code>main</code> via GitHub Actions</dd></dl></div></section>

data/build/docs/releasehx.1

@@ -1,13 +1,13 @@
 '\" t
 .\"     Title: releasehx
 .\"    Author: [see the "AUTHOR(S)" section]
-.\" Generator: Asciidoctor 2.0.23
-.\"      Date: 2025-11-06
+.\" Generator: Asciidoctor 2.0.26
+.\"      Date: 2026-05-14
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "RELEASEHX" "1" "2025-11-06" "\ \&" "\ \&"
+.TH "RELEASEHX" "1" "2026-05-14" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -29,8 +29,20 @@
 .\}
 .SH "NAME"
 releasehx \- Generate formatted release histories from Jira, GitHub, GitLab, YAML, or JSON sources.
+.if n .sp
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+.B Tip
+.ps -1
+.br
 .sp
-\fBTip:\fP Type \f(CRq\fP to exit this page.
+Type \f(CRq\fP to exit this page.
+.sp .5v
+.RE
 .SH "ALIASES"
 .sp
 \f(CRrhx\fP
@@ -251,7 +263,7 @@ Display the ReleaseHx version code.
 .RS 4
 Enrich HTML with/out head and body tags.
 When enriching to HTML, \fIinclude\fP (\f(CR\-\-wrap\fP) or \fIexclude\fP (\f(CR\-\-no\-wrap\fP) the \f(CR<head>\fP and \f(CR<body>\fP tags and their content.
-For use when the opposite value is set in the config file (\fB[conf_ppty_modes_wrapped]\fP).
+For use when the opposite value is set in the config file (\fB[conf_ppty_modes_html_wrap]\fP).
 .RE
 .sp
 \fB\-\-quiet\fP

data/build/docs/sample-config.yml

@@ -25,7 +25,9 @@ conversions: # Details about content origination, as well as markup sources and
   note: issue_body # The source of the release notes content.
 #   note_custom_field:  # The name of the custom field to use for the release notes content.Liquid error: wrong number of arguments (given 3, expected 1..2)Liquid error: wrong number of arguments (given 3, expected 1..2)
   markup: markdown # The origin markup format for notes.
-#   engine:  # The markup converter to use for the issues.
+  engines: # Specifies the conversion engines to use when enriching to various output formats.
+#     html:  # Engine for converting to HTML format.
+#     pdf:  # Engine for converting to PDF format.
 extensions: # Default file extensions.
   markdown: md # File extension for Markdown drafts.
   asciidoc: adoc # File extension for AsciiDoc drafts.
@@ -72,7 +74,7 @@ tags: # Handling for tags, labels, or toggles associated with source Issues.
     - breaking
     - experimental
     - changelog
-  _exclude: # The list of tags that cause a change/issue to be excluded from the release history.
+  _exclude: [] # The list of tags that cause a change/issue to be excluded from the release history.
   highlight: # The tag, label, or toggle that indicates an issue is to be highlighted or prioritized in sorts.
     head: Highlights # How this tag will display as a grouping title.
     text: highlight # How this tag will display as a label.
@@ -163,10 +165,10 @@ paths: # The configuration for the paths to include in the release history listi
   mappings_dir: _mappings # The path to the directory containing user-defined API mappings.
   api_clients_dir: _apis # The path to the directory containing user-defined API client definitions.
 modes: # Default settings for rhx command executions.
-  wrapped: false # Include (or exclude) head, header, and footer elements when enriching to HTML.
+  html_wrap: false # Include (or exclude) head, header, and footer elements when enriching to HTML.
   html_frontmatter: true # Include frontmatter in the rendered HTML.
   markdown_frontmatter: false # Include frontmatter in Markdown drafts.
-#   asciidoc_frontmatter:  # Include frontmatter in AsciiDoc drafts.
+  asciidoc_frontmatter: false # Include frontmatter in AsciiDoc drafts.
   fetch: notes-only # What to fetch when gathering issues from API.
   remove_excess_lines: 1 # Reduces N+ consecutive blank lines to N lines.
 rhyml: # Settings related to RHYML data objects and documents.
@@ -178,6 +180,12 @@ rhyml: # Settings related to RHYML data objects and documents.
   pasterize_head: false # Whether to convert verbs in the head property to past tense when drafting.
 history: # Configurations for the overall document, when applicable.Liquid error: wrong number of arguments (given 3, expected 1..2)
   htag: h1 # The heading level (H1, H2, etc) for the release history header.Liquid error: wrong number of arguments (given 3, expected 1..2)Liquid error: wrong number of arguments (given 3, expected 1..2)Liquid error: wrong number of arguments (given 3, expected 1..2)
+  html_framework: bare # The HTML framework to use when enriching to HTML.
+  styling: # Configuration options for HTML styling and CSS framework integration.
+    mode: framework # The HTML styling approach to use when generating wrapped HTML output.
+    theme: default # The visual theme variant to apply to HTML output.
+    embed_css: false # Include comprehensive CSS directly in the HTML <style> block.
+#     css_url:  # URL or path to external CSS stylesheet for custom styling.
   items: # Settings pertaining to displayed items across Changelog and Release Notes sections.
     allow_redundant: false # Whether to allow duplicate entries in a given section, for instance across groups for part:group sorts where a change affects...
     show_issue_links: false # Whether to include web links in item metadata.
@@ -210,8 +218,7 @@ changelog: # The configuration for the changelog output.
   head: Changelog # The header for the changelog output.Liquid error: wrong number of arguments (given 3, expected 1..2)
   htag: h2 # The heading level (H1, H2, etc) for the changelog section header.
   spot: 2 # Where in the document to place the changelog (1 = top, 2 = bottom).
-  sort: # The sort order for the changelog output.
-    - part:grouping1
+  sort: [part:grouping1] # The sort order for the changelog output.
   items: # Settings that affect the frame/shape and arrangement of individual changelog entries.
     frame: unordered # The layout for the changelog entry display.
     allow_redundant: false # Whether to allow duplicate entries in a given section, for instance across groups for part:group sorts where a change affects...
@@ -248,4 +255,4 @@ notes: # The configuration for the Release Notes listing section.
     show_parts_label: false # Whether to show the parts label in the item metadata output.
     show_tags_label: false # Whether to show the tags label in the item metadata output.
     show_lead_label: false # Whether to show the lead label in the item metadata output.
-    show_auths_label: false # Whether to show the authors label in the item metadata output.
+    show_auths_label: false # Whether to show the authors label in the item metadata output.

data/lib/releasehx/cli.rb

@@ -753,12 +753,14 @@ module ReleaseHx
       @settings['modes'] ||= {}
 
       unless options[:wrap].nil?
-        @settings['modes']['wrapped'] = options[:wrap]
+        @settings['modes']['html_wrap'] = options[:wrap]
         ReleaseHx.logger.info "✓ Changed HTML wrapping to: #{options[:wrap]}" if options[:verbose]
       end
 
       return if options[:frontmatter].nil?
 
+      @settings['modes']['markdown_frontmatter'] = options[:frontmatter]
+      @settings['modes']['asciidoc_frontmatter'] = options[:frontmatter]
       @settings['modes']['html_frontmatter'] = options[:frontmatter]
       ReleaseHx.logger.info "✓ Changed frontmatter inclusion to: #{options[:frontmatter]}" if options[:verbose]
     end
@@ -840,8 +842,9 @@ module ReleaseHx
 
       # Extract issues array if client config specifies root_issues_path: "issues"
       # This matches what the API client does when fetching live data
+      # BUT: Skip extraction if a custom mapping is provided, as it handles extraction itself
       origin_source = @settings.dig('origin', 'source')
-      if origin_source && payload.is_a?(Hash) && payload.key?('issues')
+      if origin_source && payload.is_a?(Hash) && payload.key?('issues') && !options[:mapping]
         client_path = find_api_client_config(origin_source)
         if client_path
           client_def = SchemaGraphy::Loader.load_yaml_with_tags(client_path)

data/lib/releasehx/configuration.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'psych'
-require_relative '../schemagraphy/loader'
 
 module ReleaseHx
   # Manages the application's configuration by loading and merging settings

data/lib/releasehx/generated.rb

@@ -2,7 +2,7 @@
 # Auto-generated by Sourcerer::Builder
 
 module ReleaseHx
-  ATTRIBUTES = {:globals=>{"attribute-undefined"=>"drop-line", "attribute-missing"=>"skip", "appendix-caption"=>"Appendix", "appendix-refsig"=>"Appendix", "caution-caption"=>"Caution", "chapter-refsig"=>"Chapter", "example-caption"=>"Example", "figure-caption"=>"Figure", "important-caption"=>"Important", "last-update-label"=>"Last updated", "note-caption"=>"Note", "part-refsig"=>"Part", "prewrap"=>"", "sectids"=>"", "section-refsig"=>"Section", "table-caption"=>"Table", "tip-caption"=>"Tip", "toc-placement"=>"macro", "toc-title"=>"Table of Contents", "untitled-label"=>"Untitled", "version-label"=>"Version", "warning-caption"=>"Warning", "notitle"=>"", "docfile"=>"/home/brian/Documents/work/releasehx/README.adoc", "docdir"=>"/home/brian/Documents/work/releasehx", "docfilesuffix"=>".adoc", "docname"=>"README", "embedded"=>"", "asciidoctor"=>"", "asciidoctor-version"=>"2.0.23", "safe-mode-name"=>"unsafe", "safe-mode-unsafe"=>"", "safe-mode-level"=>0, "max-include-depth"=>64, "user-home"=>"/home/brian", "doctype"=>"article", "htmlsyntax"=>"html", "backend-html5-doctype-article"=>"", "doctype-article"=>"", "backend-html5"=>"", "backend"=>"html5", "outfilesuffix"=>".html", "filetype"=>"html", "filetype-html"=>"", "basebackend-html-doctype-article"=>"", "basebackend-html"=>"", "basebackend"=>"html", "stylesdir"=>".", "iconsdir"=>"./images/icons", "localdate"=>"2026-01-30", "localyear"=>"2026", "localtime"=>"01:33:36 -0500", "localdatetime"=>"2026-01-30 01:33:36 -0500", "docdate"=>"2026-01-30", "docyear"=>"2026", "doctime"=>"00:47:36 -0500", "docdatetime"=>"2026-01-30 00:47:36 -0500", "page-layout"=>"default", "page-permalink"=>"/docs/", "page-title"=>"ReleaseHx Docs", "page-nav_order"=>"1", "doctitle"=>"ReleaseHx", "docopslab_git_www"=>"https://github.com/DocOps", "this_prod_slug"=>"releasehx", "releasehx_prod_repo"=>"https://github.com/DocOps/releasehx", "releasehx_demo_repo"=>"https://github.com/DocOps/releasehx-demo", "this_prod_repo"=>"https://github.com/DocOps/releasehx", "this_prod_vrsn_major"=>"0", "this_prod_vrsn_minor"=>"1", "this_prod_vrsn_major-minor"=>"0.1", "this_prod_vrsn_patch"=>"2", "this_prod_vrsn"=>"0.1.2", "next_prod_vrsn"=>"0.2.0", "tagline"=>"Generate formatted release histories from Jira, GitHub, GitLab, YAML, or JSON sources.", "description"=>"CLI utility and Ruby API for generating structured release notes and changelog documents from various issue-tracking platforms or YAML definitions into plaintext drafts (<strong>AsciiDoc</strong>, <strong>Markdown</strong>, <strong>YAML</strong>) and rich-text output (<strong>HTML</strong> and <strong>PDF</strong>).", "gem_config_definition_path"=>"./specs/data/config-def.yml", "app_default_config_path"=>"./.releasehx.yml", "default_markup"=>"markdown", "default_slug_type"=>"kebab", "default_tplt_lang"=>"liquid", "default_drafts_dir"=>"_drafts", "default_enrich_dir"=>"_publish", "default_output_dir"=>".", "default_payloads_dir"=>"_payloads", "default_templates_dir"=>"_templates", "default_mappings_dir"=>"_mappings", "default_api_clients_dir"=>"_apis", "default_cache_dir"=>".releasehx/cache", "default_api_cred_env"=>"RELEASEHX_API_CRED", "default_api_key_env"=>"RELEASEHX_API_KEY", "default_api_user_env"=>"RELEASEHX_API_USER", "default_api_org_env"=>"RELEASEHX_API_ORG", "markdown_extensions"=>".md, .markdown", "asciidoc_extensions"=>".adoc, .ad, .asciidoc", "yaml_extensions"=>".yml, .yaml, .rhyml", "draft_source_file_types"=>"AsciiDoc, Markdown, YAML", "draft_source_extensions"=>".md, .markdown, .adoc, .ad, .asciidoc, .yml, .yaml, .rhyml", "enrich_file_types"=>"HTML, PDF", "enrich_extensions"=>".html, .pdf", "docker_base_command"=>"docker run -it --rm --user $(id -u):$(id -g) -v $(pwd):/workdir docopslab/releasehx rhx", "this_prod_repo_branch"=>"https://github.com/DocOps/releasehx/tree/release/0.1", "docs_extn"=>"", "toc"=>"", "toclevels"=>"3", "authorcount"=>0, "toc-position"=>"content"}}
+  ATTRIBUTES = {:globals=>{"attribute-undefined"=>"drop-line", "attribute-missing"=>"skip", "appendix-caption"=>"Appendix", "appendix-refsig"=>"Appendix", "caution-caption"=>"Caution", "chapter-refsig"=>"Chapter", "example-caption"=>"Example", "figure-caption"=>"Figure", "important-caption"=>"Important", "last-update-label"=>"Last updated", "note-caption"=>"Note", "part-refsig"=>"Part", "prewrap"=>"", "sectids"=>"", "section-refsig"=>"Section", "table-caption"=>"Table", "tip-caption"=>"Tip", "toc-placement"=>"macro", "toc-title"=>"Table of Contents", "untitled-label"=>"Untitled", "version-label"=>"Version", "warning-caption"=>"Warning", "notitle"=>"", "docfile"=>"/home/brian/Documents/work/releasehx/README.adoc", "docdir"=>"/home/brian/Documents/work/releasehx", "docfilesuffix"=>".adoc", "docname"=>"README", "embedded"=>"", "asciidoctor"=>"", "asciidoctor-version"=>"2.0.26", "safe-mode-name"=>"unsafe", "safe-mode-unsafe"=>"", "safe-mode-level"=>0, "max-include-depth"=>64, "user-home"=>"/home/brian", "doctype"=>"article", "htmlsyntax"=>"html", "backend-html5-doctype-article"=>"", "doctype-article"=>"", "backend-html5"=>"", "backend"=>"html5", "outfilesuffix"=>".html", "filetype"=>"html", "filetype-html"=>"", "basebackend-html-doctype-article"=>"", "basebackend-html"=>"", "basebackend"=>"html", "stylesdir"=>".", "iconsdir"=>"./images/icons", "localdate"=>"2026-05-27", "localyear"=>"2026", "localtime"=>"11:16:48 -0400", "localdatetime"=>"2026-05-27 11:16:48 -0400", "docdate"=>"2026-05-27", "docyear"=>"2026", "doctime"=>"10:37:27 -0400", "docdatetime"=>"2026-05-27 10:37:27 -0400", "page-layout"=>"default", "page-permalink"=>"/docs/", "page-title"=>"ReleaseHx Docs", "page-nav_order"=>"1", "doctitle"=>"ReleaseHx", "this_proj_slug"=>"releasehx", "this_proj_name"=>"ReleaseHx", "docopslab_src_www_url"=>"https://raw.githubusercontent.com/DocOps", "docopslab_domain"=>"docopslab.org", "docopslab_www_url"=>"https://docopslab.org", "docopslab_io_www_url"=>"https://docopslab.github.io", "docopslab_ruby_version"=>"3.2.7", "docopslab_git_src_uri"=>"git@github.com:DocOps", "this_proj_src_www_url"=>"https://raw.githubusercontent.com/DocOps/releasehx", "this_proj_src_raw_url"=>"https://raw.githubusercontent.com/DocOps/releasehx/main", "this_proj_src_main_files_url"=>"https://raw.githubusercontent.com/DocOps/releasehx/blob/main", "this_proj_src_main_edit_url"=>"https://raw.githubusercontent.com/DocOps/releasehx/edit/main", "this_proj_src_git_uri"=>"git@github.com:DocOps/releasehx.git", "this_proj_ruby_version"=>"3.2.7", "extn"=>"", "releasehx_demo_repo"=>"https://raw.githubusercontent.com/DocOps/releasehx-demo", "this_prod_slug"=>"releasehx", "this_prod_vrsn_major"=>"0", "this_prod_vrsn_minor"=>"2", "this_prod_vrsn_majmin"=>"0.2", "this_prod_vrsn_patch"=>"0", "this_prod_vrsn"=>"0.2.0", "next_prod_vrsn"=>"0.3.0", "next_prod_vrsn_majmin"=>"0.3", "tagline"=>"Generate formatted release histories from Jira, GitHub, GitLab, YAML, or JSON sources.", "description"=>"CLI utility and Ruby API for generating structured release notes and changelog documents from various issue-tracking platforms or YAML definitions into plaintext drafts (<strong>AsciiDoc</strong>, <strong>Markdown</strong>, <strong>YAML</strong>) and rich-text output (<strong>HTML</strong> and <strong>PDF</strong>).", "gem_config_definition_path"=>"./specs/data/config-def.yml", "app_default_config_path"=>"./.releasehx.yml", "docker_run_command"=>"docker run -it --rm --user $(id -u):$(id -g) -v $(pwd):/workdir docopslab/releasehx rhx", "default_markup"=>"markdown", "default_slug_type"=>"kebab", "default_tplt_lang"=>"liquid", "default_drafts_dir"=>"_drafts", "default_enrich_dir"=>"_publish", "default_output_dir"=>".", "default_payloads_dir"=>"_payloads", "default_templates_dir"=>"_templates", "default_mappings_dir"=>"_mappings", "default_api_clients_dir"=>"_apis", "default_cache_dir"=>".releasehx/cache", "default_api_cred_env"=>"RELEASEHX_API_CRED", "default_api_key_env"=>"RELEASEHX_API_KEY", "default_api_user_env"=>"RELEASEHX_API_USER", "default_api_org_env"=>"RELEASEHX_API_ORG", "markdown_extensions"=>".md, .markdown", "asciidoc_extensions"=>".adoc, .ad, .asciidoc", "yaml_extensions"=>".yml, .yaml, .rhyml", "draft_source_file_types"=>"AsciiDoc, Markdown, YAML", "draft_source_extensions"=>".md, .markdown, .adoc, .ad, .asciidoc, .yml, .yaml, .rhyml", "enrich_file_types"=>"HTML, PDF", "enrich_extensions"=>".html, .pdf", "asciisourcerer_www_url"=>"https://raw.githubusercontent.com/DocOps/asciisourcerer", "schemagraphy_www_url"=>"https://raw.githubusercontent.com/DocOps/schemagraphy", "toc"=>"", "toclevels"=>"3", "authorcount"=>0, "toc-position"=>"content"}}
 
   SNIPPET_LOOKUP = {"helpscreen"=>"helpscreen.txt"}