releasehx 0.1.1 → 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/releases.adoc

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Releases
+nav_order: 90
+permalink: /docs/releases/
+---
+= Release History
+:page-layout: default
+:page-title: Releases
+:page-nav_order: 90
+:page-permalink: /docs/releases/
+
+Complete release history for ReleaseHx, generated using ReleaseHx itself.
+
+ifdef::env-site[]
+// Generated during prebuild - includes release index and content
+include::_release_index.adoc[]
+endif::[]
+
+ifndef::env-site[]
+== Development Mode
+
+Release history is generated during the prebuild process. Run `bundle exec rake prebuild` to generate the full release index.
+endif::[]
+
+---
+
+For more information about ReleaseHx, see the link:/docs/[main documentation].

data/build/docs/sample-config.adoc

@@ -1,4 +1,6 @@
 :page-nav_order: 3
+:page-permalink: /docs/sample-config/
+:page-redirect_from: /sample-config.html
 = Sample Configuration File
 
 This is a "`kitchen sink`" example of the ReleaseHx configuration settings.

data/build/docs/sample-config.yml

@@ -22,10 +22,12 @@ origin: # The API or file source for the issues.
 conversions: # Details about content origination, as well as markup sources and conversion.
   summ: issue # The source of the summary (Changelog) content.
 #   head:  # The source of release-note headlines, when it is not the same as the summary.
-#   note:  # The source of the release notes content.
+  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.
@@ -195,7 +203,7 @@ history: # Configurations for the overall document, when applicable.Liquid error
     type_label: type # The label to use for the type of change.
 #     type_icon:  # The icon to use for the type of change.
     parts_label: Components # The label to use for the part/component affected by the change.
-    part_label: Part # The label to use for the singular part/component affected by the change, when only one part is permitted.
+    part_label: Component # The label to use for the singular part/component affected by the change, when only one part is permitted.
     parts_icon: puzzle-piece # The icon to use for the part/component affected by the change.
     tags_label: # The tags associated with the change, if any.
       - Tags
@@ -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.