ReleaseHx

API → Markdown/AsciiDoc/YAML → HTML/PDF

rhx 2.1.0 --yml
rhx 2.1.0 --append
rhx 2.1.0 --adoc

gem install releasehx

The rhx-mcp command starts a local MCP server that exposes ReleaseHx configuration resources for AI clients over STDIO. MCP is still new, so use the setup guidance below.

Resources

releasehx://agent/guide

Short guide for agent usage and navigation.

releasehx://config/sample

Sample config tree with defaults and comments.

releasehx://config/schema

Authoritative CFGYML definition.

releasehx://config/reference.json

JSON reference document for tooling.

releasehx://config/reference.adoc

AsciiDoc reference document.

Tool

config.reference.get

Accepts a JSON Pointer (example: /properties/origin) and returns the reference entry.

Choose how to run the MCP server:

Docker (recommended)

Bundled gem

Global gem

If you want to play around with ReleaseHx before connecting it to your own Issues source via API, use the DocOps/releasehx-demo repository as instructed in this section.

Alternately, skip to Establishing Issues Source to begin configuring your own project/environment.

1. Clone the demo repository.

   git clone git@github.com:DocOps/releasehx-demo.git

2. Change to the new repo directory.

   cd releasehx-demo

3. Install ReleaseHx and dependencies.

   bundle install

4. Run the rhx command with special arguments. For example:

   bundle exec rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --md demo-1.1.0.md

   Prepend bundle exec if using the local project Ruby installation.

In this example, the jira-customfield-note-1.1.0.json file fills in for the version 1.1.0 issue tickets in a Jira project, drafting them as a local Markdown file.

The demo repo contains several JSON files that simulate the data returned by the Jira, GitHub, and GitLab APIs.

The demo repository also comes with a number of configuration arrangements, which you may switch to or freely edit.

Try the following series of commands and steps to see ReleaseHx in action.

1. Check for issues missing release notes.

   rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --check

   Out of the box, there are two issues in the jira-customfield-note-1.1.0.json file that are marked release_note_needed yet have no release note filled out.

2. Generate a YAML draft.

   rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --yaml

3. Edit the YAML draft in any way, then save.

4. Add release notes to the two issues that were missing them in _payloads/jira-customfield-note-1.1.0.json.

5. Update the YAML draft with the new issues.

   rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --append

6. Generate a Markdown draft.

   rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --md

7. Edit the Markdown draft in any way.

8. Generate HTML and PDF output.

   rhx 1.1.0 --config configs/jira-customfield.yml --api-data _payloads/jira-customfield-note-1.1.0.json --html --pdf

For more on the demo repo, visit its README at https://github.com/DocOps/releasehx-demo.

Your own application will require at least some customization. Once configured, the commands you use day-to-day, or release-to-release, will become relatively simple.

If any of the demo configs seems like the right arrangement for you, copy it to your project directory and modify it to further suit your needs.

See the Application Configuration Reference for an annotated list of available settings.

ReleaseHx uses platform-specific environment variables for API authentication. Set the appropriate variables for your platform:

ReleaseHx can connect to the Jira REST API to fetch issues that match the release version.

The Issue summary field is used to draft the Changelog/title, and a custom field called release_note is used for the Release note.

In Jira, what ReleaseHx calls “tags” can be assigned using either Jira labels or checkbox custom fields.

ReleaseHx can connect to the GitHub Issues API to fetch issues from the release version.

The issue title field is used to draft the Changelog/title, and any text in the body that follows text like # Release Note is used for the Release note.

In GitHub, what ReleaseHx calls “tags” can be assigned using labels or checkboxes embedded after the Release Note text.

ReleaseHx can connect to the GitLab Issues API to fetch issues from the release version.

The issue title field is used to draft the Changelog/title, and any text in the body that follows text like # Release Note is used for the Release note.

In GitLab, what ReleaseHx calls “tags” can be assigned using labels or checkboxes embedded after the Release Note text.

ReleaseHx is extensible. While it officially supports Jira, GitHub, and GitLab, you can configure it to connect to any issue-tracking system with a REST API.

Use the application config file to designate an API endpoint and any required authentication. Then provide a mapping file at _mappings/<api_from_name>.yml (or the path configured at [conf_ppty_paths_mappings_dir]) to define the data conversion to RHYML.

See Custom REST API Client Configuration for details.

Use a locally stored YAML file as the source of your Release History and Changelog content. This is essentially the same document that is drafted from a REST API source by the --yaml flag for the rhx command.

All issues associated with a given release are nested together under a work: property without further hierarchy. Since the entries are data, they can be organized here however you wish, then re-sorted upon generating a Markdown or AsciiDoc draft, or going directly to PDF or HTML.

The advantage of this method is working without an API. Contributors can simply add their notes to a unified file via Git, and that file can be edited in place.

The RHYML content can be connected to Issues and Git commits, but only tangentially. The summary and note content needs to be listed in the YAML document. Links back to the source issue or commit are possible but optional.

draft/drafting

The process of creating a file in lightweight markup format, such as AsciiDoc, Markdown, or YAMLL, which is intended to be manually edited by the user. Drafting operations happen to use templates to render output, but we use the term draft whenever the output format is lightweight markup intended for manual editing.

enrich/enrichment

These terms describe the process of turning data or a draft into a rich-text output format, such as HTML or PDF.

Some utilities consider this “rendering”, but render is a term hard-coded into Liquid and Tilt operations, so we use it to describe the act of generating text with a templating engine. Likewise, the term “convert” is integral to Asciidoctor and Pandoc operations, and we don’t want to confuse them.

render/rendering

The final step in converting a template (such as Liquid and ERB) into its target format (such as Markdown, AsciiDoc, or HTML). Render operations transform textual content but do not necessarily change formats. The focus is on the process, not the output.

In ReleaseHx, you will see this mostly in the context of templated configuration fields and the like, even though drafting operations all technically involve rendering.

convert/conversion

Generally the transformation from one file format to another. We reserve these terms for specific use with respect to third-party tools such as Asciidoctor and Pandoc. Converters read standardized markup to produce a wide variety of outputs. This typically means converting Markdown or AsciiDoc to HTML or PDF, but it is also used to refer to transforming Markdown to AsciiDoc and other such operations.

We use the term issues to describe the tasks tracked by your cloud-based issue-management system (IMS), such as Jira or GitHub Issues.

A change is the ReleaseHx term for the report that something is changed in the subject product.

ReleaseHx uses issue to refer to the state in the source/API, and change to refer to the record of a product change in RHYML — the Release History YAML-based Modeling Language. Issues get turned into changes, a subtle but important difference.

Likewise, version and release are somewhat interchangeable. Version is the associative reference, typically the way software changes are identified in Git (branch), GitHub Issues (milestone) or Jira (fixVersion).

Whereas release is more of the concept of a revision of the subject product, and it is represented by a property in RHYML listed in an Array called releases.

Typically, ReleaseHx refers to a release as the subject of a “Release History”, and version or version code is the way a release is identified.

A code is the literal string used to identify a version or release. In RHYML, code is the property of a release that identifies the version.

REST API

A remote, HTTP-based service, in our case used as the source for issue data. In certain contexts, this is shorthanded as simply API.

ReleaseHx API

The Ruby library that provides the ReleaseHx functionality for downstream Ruby applications, including the rhx CLI (command-line interface).

source

In ReleaseHx parlance, this is the means, location, and format of the data that will be used to generate a Release History. Typically a REST API, this could also be a local YAML file or a Git repository.

API client

A local utility or component that is able to connect to a REST API and retrieve data from it.

For designating what to output, the following blocks or properties in the config file are relevant:

history

This block defines the overall document and establishes defaults that apply to notes and changelog sections.

notes

This block defines the Release Notes output.

changelog

This block defines the Changelog output.

For more, see Application Configuration Reference and Advanced Template Configuration.

Place templates in the directory established in paths.templates_dir in the config (defaults to ./_templates).

Templates replace their namesakes built into the ReleaseHx application or API.

By default, ReleaseHx expects templates to be formatted in Liquid, but it uses the Jekyll-enhanced Liquid 4. See [templating] for details.

If your team uses a supported issue-management system (Jira, GitHub Issues, or GitLab Issues), you will almost certainly wish to integrate that platform.

Additionally, assuming your team uses Git, you may wish to derive content from Git commits. This is only the case if your commit messages are suited to including drafts of release notes or changelog entries, which is fairly rare.

Generally, you will derive change summaries, notes, and metadata from your IMS, but hybrid sourcing (with Git) is readily configurable. Since you operate ReleaseHx in your product repository, it uses Git directly on your system rather than relying on your cloud-hosted Git service.

Once the relevant “issues” have been derived from your API or Git, they become “changes” in ReleaseHx terminology, and they are held as a data object in RHYML format.

At this point, these changes can be converted to YAML, Markdown, or AsciiDoc so you can tinker with them. This process is called “drafting” — it compiles your changes into one document.

The recommended procedure is to use YAML at this phase. Only the YAML format maintains the changes as data and as a single source of truth. If you make a change in the RHYML/YAML document, you can still readily convert to Markdown or AsciiDoc at any point.

Edit-at-source method

However, if you are confident in the overall shape of your issues at the source, drafting directly to Markdown or AsciiDoc, or even converting directly to HTML or PDF, are available options.

Indeed, if you wish to do all of your editing in the IMS interface, this is the way to go. You can generate Markdown or HTML, review, and make further changes to the IMS issues, then re-fetch and generate anew.

If your team works in a continuous-deployment environment, you may wish to maintain one ongoing Release History.

To do so, modify your API request template with some logical filter, and always use the --append option, drafting to YAML.

Continuous deployment environments will likely get better treatment in this application prior to the 1.0 release. I just don’t have enough experience with them to predict the optimal workflow.

Usage: rhx VERSION|FILE [options]

Options:
  --md [PATH]            Draft to Markdown
  --adoc, --ad [PATH]    Draft to AsciiDoc
  --yaml, --yml [PATH]   Draft to YAML
  --html [PATH]          Enrich to HTML
  --pdf [PATH]           Enrich to PDF
  --output-dir PATH      Establish base target path for generated files
  --api-data PATH        Ingest from a JSON file instead of REST response

  --config PATH          Config location (default: ././.releasehx.yml)
  --mapping PATH         Alternate API mapping location
  --payload PATH         Store payload as JSON file at PATH or default
  --fetch                Refresh data from source
  --append               Add any new issues to the end of local YAML source
  --over, --force        Overwrite any existing files without prompting
  --check, --scan        Find issues with missing release note
  --empty, -e [RULE]     Set/reverse policy on issues "awaiting notes"
  --internal             Include issues marked internal or likewise
  --[no-]wrap            Enrich HTML with/out head and body tags
  --[no-]frontmatter     Enrich or draft with/out frontmatter

  --manpage, --man       Show the full manpage documentation
  --verbose              Express each step to console
  --debug                Express each step and show inferred states
  --debug-dump           Complete debugging with raw data
  --quiet                Suppress all output, including warnings
  --version              Display the ReleaseHx version code

ReleaseHx enables several workflow combinations for drafting and enriching release histories.

The API element of the above workflows could be a RHYML file, in which case the API → YAML conversions are unnecessary, as the YAML step in those workflows is a proper RHYML document already.

Most of the workflow cases can be executed using fairly straightforward command combinations.

Take this API → Markdown → HTML/PDF workflow for instance:

1. Ensure all release notes are added in the IMS source.

   rhx 2.1.0 --check

2. Create a Markdown draft from API data.

   rhx 2.1.0 --md

3. Edit and save the Markdown draft.

4. Enrich HTML and PDF files from the Markdown draft.

   rhx 2.1.0 --html --pdf

But for cases where you wish to draft/edit in YAML and then in Markdown or AsciiDoc, such as API → YAML → AsciiDoc → HTML/PDF, the following series of steps is exemplary:

1. Create a YAML draft from API data.

   rhx 2.1.0 --yaml

2. Edit and save the YAML draft.

3. Add any newly annotated issues to the end of the YAML draft.

   rhx 2.1.0 --append

4. Create an AsciiDoc draft from the YAML draft.

   rhx 2.1.0 --adoc

   Note	ReleaseHx looks for 2.1.0.yml and creates an AsciiDoc draft like 2.1.0.adoc.

5. Edit that draft as AsciiDoc and save.

6. Enrich HTML and PDF from the AsciiDoc draft.

   rhx 2.1.0 --html --pdf

   Note	ReleaseHx finds both 2.1.0.yml and 2.1.0.adoc, choosing the latter.

It is also possible to source directly in RHYML files and draft to Markdown or AsciiDoc or else directly to HTML/PDF.

Certain CLI arguments and options will take precedence over others, especially in determining what sources are actively used during a given operation.

ReleaseHx determines the data source using the following priority order, where higher priority options override lower priority ones:

The following options are available for the releasehx/rhx commands.

--adoc, --ad [PATH]

Draft to AsciiDoc. Outputs to <drafts_dir>/<file_template> or <PATH>.

Where <drafts_dir> is the value of paths.drafts_dir in the config, and <template> is the value of templates.drafts_filename in the config.

--api-data PATH

Ingest from a JSON file instead of REST response. Point to any local JSON source file that is formatted like a response payload for your configured API (see [conf_ppty_origin_source]); this overrides the normal REST request even if --fetch is argued (though a warning will appear if you pass both options).

--append

Add any new issues to the end of local YAML source.

When drafting in YAML, adds new issues to the end of the file. Be sure to save edits before appending.

--check, --scan

Find issues with missing release note. Scans issues for those missing release notes and reports findings.

--config PATH

Config location (default: ././.releasehx.yml). Use the configuration file at the specified path instead of the default location (./.releasehx.yml).

--debug

Express each step and show inferred states. Conveys all INFO and DEBUG messages.

--debug-dump

Complete debugging with raw data. Includes all INFO and DEBUG output, as well as raw data objects.

--empty, -e [RULE]

Set/reverse policy on issues "awaiting notes".

Argue a specific drafting policy, or argue the “opposite” policy, for handling issues that are marked as release_note_needed but no note is provided. Set a specific rule (skip, empty, dump, or ai`) to have ReleaseHx include the issue when converting issues to changes, even if no expected note content has been added.

Using -e dump will draft the issue with the entire issue body and commit message as the note content, for any qualifying change entry. Whereas -e ai will use generative AI to draft note properties from issue body and commit message.

Otherwise use just --empty or -e to toggle between skip and empty, if either of those is your default in [conf_ppty_rhyml_empty_notes]. If your default is blank, dump, or ai, using --empty or -e with no argument will toggle a skip policy.

--fetch

Refresh data from source.

Retrieves fresh data rather than using cached/draft files when converting to HTML/PDF. Typically used like:

rhx 1.1.0 --fetch --html

The fetch procedure does write a cached RHYML document before generating final output.

--frontmatter, --no-frontmatter

Enrich or draft with/out frontmatter. When generating drafts or enriching to HTML output, include (--frontmatter) or exclude (--no-frontmatter) frontmatter.

--html [PATH]

Enrich to HTML. Writes to <output_path>/<file_template> or <PATH>.

--internal

Include issues marked internal or likewise. Include issues marked as internal or similarly restricted when drafting content. Has no effect on enrichment operations.

--api-data PATH

Ingest from a JSON file instead of REST response. For API responses, this option saves the payload as PATH. During normal output generating, this option writes a copy of RHYML object to PATH.

--md [PATH]

Draft to Markdown. Outputs to <drafts_dir>/<file_template> or <PATH>.

Where <drafts_dir> is the value of paths.drafts_dir in the config, and <template> is the value of templates.drafts_filename in the config.

--manpage, --man

Show the full manpage documentation. Includes this options reference and other documentation, all in the terminal.

Tip	Use q to quit back to prompt.

--mapping

Alternate API mapping location. File must be a valid RHYML mapping config, usually stored at _mapping/<apiname>.yaml.

The mapping base directory can be changed in [conf_ppty_paths_mappings_dir], but this option must include a complete relative or absolute path.

--payload [PATH]

Store payload as JSON file at PATH or default If no path is argued, defaults to that set in [conf_ppty_paths_payloads_dir].

--output-dir DIRECTORY

Establish base target path for generated files.

--over, --force

Overwrite any existing files without prompting. When writing files, overwrite existing files without prompting for confirmation.

--pdf [PATH]

Enriches to PDF from default or designated source. Writes to <output_path>/<file_template> or <PATH>.

--scan, --check

Find issues with missing release note. Scans issues for those missing release notes and reports findings..

--verbose

Express each step to console during execution.

--version

Display the ReleaseHx version code.

--wrap, --no-wrap

Enrich HTML with/out head and body tags. When enriching to HTML, include (--wrap) or exclude (--no-wrap) the <head> and <body> tags and their content. For use when the opposite value is set in the config file ([conf_ppty_modes_wrapped]).

--quiet

Suppress all output, including warnings.

--yaml, --yml [PATH]

Draft to YAML. Outputs to <drafts_dir>/<file_template> or <PATH>.

Where <drafts_dir> is the value of paths.drafts_dir in the config, and <template> is the value of templates.drafts_filename in the config.

The two required properties for a release are code (version ID) and changes, but a release can also have a date and a memo.

code

The version identifier string. (Required.)

date

A proper date formatted as YYYY-MM-DD.

memo

An open text field for any description of the release you wish to appear in the overall release entry. Memos can be formatted with Markdown or AsciiDoc. This format must be set either in an individual RHYML file or configured at [conf_ppty_rhyml_markup].

changes

Every valid Release object must contain an Array containing at least one change entry. (Required.)

A release may include any number of changes (including zero). Within each “change” entry, the following properties are available:

chid

The change identifier. This is a contiguous String (no spaces) that MUST be among all changes in its own release and is recommended to be universally unique (across all releases).

tick

The issue ticket number for the change.

hash

The commit hash for the change.

type

The type of change. Must be registered in the types block of the config.

part

The component, interface, feature, or aspect of the product affected by the change. Must be registered in the parts block of the config.

Note	If more than one part is affected, use the parts property instead.

parts

When more than one component, interface, feature, or aspect of the product is affected by the change, and you wish all such “parts” to be noted, use this property instead of part. All items must be listed in the parts block of the config.

summ

A brief summary of the change. Typically used as the Changelog entry.

head

The headline for a release note, if the value of the summ property is not preferred. In standard templates, the headline placeholder looks for a head property but falls back to summ.

note

A note about the change. May include markup formatting.

tags

An array of tags associated with the change. Each must be registered in the tags block of the config. Several tags are registered by default, but you can add as many as you like.

links

A list of documentation or marketing links for the change. The xref and href properties are mutually exclusive; href will supersede.

lead

The primary contributor to the change. Associated with a username in the Issues system.

auths

An array of contributors to the change. Each item must have a user property that matches a username in the Issues system, and may have a memo property to describe the user’s role or involvement in the change.

Common flags used with ReleaseHx patterns:

m (multi-line)

Makes ^ and $ match line boundaries instead of just start/end of string. Important for matching within paragraphs.

s (dotall)

Makes dot (.) match newlines. Often needed for note extraction across paragraphs.

i (case insensitive)

Makes pattern case-insensitive. Rarely needed in ReleaseHx patterns.

All these are equivalent and will match a Release Note heading and capture its content:

The RegexpUtils module will normalize any of these formats and apply the appropriate flags.

The ruby key provides a powerful way to perform complex data transformations using a secure, sandboxed Ruby environment. This sandbox is powered by the SchemaGraphy::SafeTransform class, which ensures that only an explicit allowlist of safe methods and language features can be used.

In some cases, the default mappings for supported APIs may not match your particular issue management setup. This commonly occurs when:

• Your GitHub Issues don’t use native issue types, relying instead on labels like type:bug, type:feature, or just bug and feature.

• Your GitLab instance has a non-standard label taxonomy.

• You need to extract data from different API response fields

ReleaseHx addresses this through alternate mapping configurations that override the default field extraction logic.

Before messing with Liquid templates at all, try experimenting with the advanced configuration features available for manipulating the output of your drafts and enriched output.

Using the ReleaseHx config file, you can manipulate:

• the order in which Changelog and Release Notes sections appear, or if either does not appear at all

• the inclusion or exclusion of internal changes, experimental features, or breaking changes

• the formatting of section headers, entry headlines, and metadata fields

• the sorting and grouping of entries by type, component, contributor, or tags

• the presence and formatting of links to issues, commits, or external documentation

• the use of custom “frames” for release notes and changelog entries

• the display of contributor information, such as lead developer

• the configuration of frontmatter

• lots more!

Most of this can be manipulated using the following sections: [conf_ppty_history], [conf_ppty_changelog], [conf_ppty_notes], [conf_ppty_links], as well as within change-metadata config blocks, where you can alter labels, icons, and such: [conf_ppty_types], [conf_ppty_parts], [conf_ppty_tags].

The various sample configurations found in the demo repository illustrate many of these options.

A complete sample config displays default values and commented descriptions of all available properties.

ReleaseHx uses Jekyll’s version of the include tag, rather than Liquid’s. It also supports Jekyll’s include_relative tag.

See Jekyll’s docs for more information.

This works essentially like Liquid 5’s render tag, which is not available in ReleaseHx.

ReleaseHx supports a tag called embed which takes no arguments and works exactly like Liquid’s include tag. The embedded file has access to all the variables in the parent template and passes any newly created or modified variables back to affect any subsequent content in the parent template.

These filters can be added to Liquid’s prime list of filters and Jekyll’s extended filters. Jekyll filters always supercede same-named Liquid filters, including where.

plusify

Replace double line breaks (\n\n) with \n+\n.

example

{{ note | plusify }}

md_to_asciidoc

Uses Kramdown-AsciiDoc (Kramdoc) to convert Markdown to AsciiDoc.

arguments

wrap

How to handle line wrapping. Can be 'preserve', 'ventilate', or 'none'. The ventilate option presents places all sentences on their own lines.

example

{{ note | md_to_asciidoc: "ventilate" }}

render

Renders a string as a Liquid template with the provided variables.

arguments

vars

A Map (Hash) of variables to pass to the template.

example

{{ note | render: vars }}

indent

Indents each line of the input by the specified number of spaces.

arguments

spaces

The number of spaces to indent by.

line1

If true, also indents the first line.

example

{{ note | indent: 2, true }}

sgyml_type

Returns a string representing the SGYML kind and class of the input, separated by a colon (:).

Response will be one of the following:

• Null:nil

• Scalar:String

• Scalar:Number

• Scalar:DateTime

• Scalar:Boolean

• Compound:Array

• Compound:ArrayList

• Compound:ArrayTable

• Compound:Map

• Compound:MapTable

• unknown:unknown

example

{{ id | type_check }}

ruby_class

Returns the Ruby class name of the input.

example

{{ id | ruby_class }}

demarkupify

Simplifies any Markdown and AsciiDoc syntax in the inline input.

Strips * and _ quotes, simplifies "` and '` quotes and UTF-8 curly quotes, and removes all backticks. example::: {{ note | demarkupify }}

pasterize

Converts select verbs in the input from present/imperative to past tense.

Replaces common terms like add/adds with added, fix/fixes with fixed, build/builds with built, etc. example::: {{ summary | pasterize }}

inspect_yaml

Returns a YAML representation of the input for debugging purposes.

example

{{ changes | inspect_yaml }}

Symptoms

ReleaseHx reports successful data transformation (ex:, INFO: Transformed 5 changes for release 1.1.0) but generated files contain only headers and template text with no actual issue content.

Root Cause

Invalid sort configuration syntax in notes: or changelog: sections.

Solution

Check your config’s sort: arrays for invalid grouping1/grouping2/grouping3 syntax.

Invalid sort configuration

# Will cause empty content
sort:
  - 'part:grouping1'
  - 'type:grouping2'

Correct sort configuration

sort:
  - 'part:group'
  - 'type:group'

Symptoms

ReleaseHx cannot transform any data from the API payload.

Root Cause

Incorrect tag filtering excluding all issues, or mapping/payload mismatch.

Solution

1. Check tags._exclude lists - never exclude release_note_needed (workflow flag)

2. Verify the payload file exists and matches the expected API format

3. Ensure custom mappings are correctly specified with --mapping option

4. Test with a simpler config without complex tag filtering

Symptoms

Errors like Liquid::SyntaxError or Liquid::Error when generating drafts or enriched output.

Root Cause

Syntax errors in custom Liquid templates.

Solution

1. Validate Liquid syntax using online validators or IDE plugins

2. Test templates with minimal content to isolate issues

3. Review Jekyll’s Liquid documentation for supported tags and filters

From the releasehx repository:

1. Install dependencies and build the gem locally.

   cd releasehx
   bundle install
   bundle exec rake build

   This creates the gem file in the pkg/ directory.

2. Install the locally built gem for testing.

   gem install pkg/releasehx-*.gem

   Alternatively, for development testing without installing:

   bundle exec bin/rhx --version

3. Run the test suite to verify functionality.

   bundle exec rake spec

From the releasehx-demo repository:

1. Install the latest gem version (published or local).

   cd releasehx-demo
   bundle install

   If testing a local gem build, update the Gemfile to point to your local gem path.

2. Execute releasehx commands against demo data.

   bundle exec rhx <your arguments and options>

   Replace <your arguments and options> with whatever you are testing. See the releasehx-demo repo’s README for example commands.

3. Generate sample outputs (for the samples branch).

   Example commands to generate outputs

   bundle exec rhx draft --source github --version v1.2.0
   bundle exec rhx enrich --input _drafts/v1.2.0.rhyml --format html

   By convention/default, drafts are written to _drafts/ and rich-text outputs to _publish/. These directories are ignored on the main branch but form the entire content of the samples branch.

CLI options are not defined in the traditional way. To maintain DRY sourcing, make your changes in the following files:

1. README.adoc: Descriptions are single sourced as AsciiDoc attributes:

   1. Add summary description to the // tag::helpscreen_attrs[] block.

   2. Add detailed description to the cli-options-ref section.

2. lib/releasehx/cli.rb

   1. Use the Thor DSL to define the option, referencing the AsciiDoc attributes for description.

   2. Add the handling code.

3. Add tests in specs/tests/rspec/cli_spec.rb.

To build the documentation locally, run the following command from the project root:

This will generate the documentation in the build/docs directory.

To serve the documentation locally, run the following command from the project root:

This will start a Jekyll server at http://localhost:8000 by default.

Use PORT=NNNN environment argument to specify a different port.

Special dev Rake tasks and libraries are available via the docopslab-dev gem.

The DocOps Lab Devtool or see .agent/docs/topics/docpslab-devtool.

SchemaGraphy provides attribute resolution capabilities through the AttributeResolver component. This enables YAML files to reference external attributes using placeholder syntax like {attribute_name}.

When loading YAML with .load_yaml_with_attributes(file_path, attributes), SchemaGraphy:

1. Loads the YAML file normally

2. Searches for {attribute_name} patterns in String values

3. Replaces them with corresponding values from the provided attributes Hash

4. Returns the resolved YAML data structure

This is used extensively in ReleaseHx’s configuration system to enable single-sourcing of defaults from README attributes.

To enable end users to pass meta-instructions along with their data, wherever it will make sense to do so, SchemaGraphy offers a straightforward handling system.

Wherever you parse YAML-formatted data using .load_yaml_with_tags, custom-tagged Scalar nodes are converted into Maps like so:

Developers may therefore conditionally interpret ingested data based on user-defined classifications, wherever the developer supports such things.

Whether a Scalar has been transformed into a TagMap, you can resolve it using:

When tags are used this way, to convey a syntax/engine for processing a template or other dynamic content, SchemaGraphy can even help us handle the content in the manner designated by the tag. This will come up again in the next section.

We are calling these “templated fields” to specify that we are talking about enabling end users to use Liquid, ERB, or eventually other templating syntaxes in YAML node values.

In so doing, developer are able to designate that the value of certain YAML nodes should be handled by a templating engine, as well as when and how.

We’ll look at how this is done in Dynamic Templated-field Handling. For now, the point is that sometimes files like specs/data/config-def.yml or an API-mapping file call for a little more runtime dynamism than a low-code solution like pure YAML can support.

Therefore, when the value of a user-configurable or environment-deterimined “setting” is a string that must be generated from data defined outside that field, we parse and render the template at runtime, using data from the environment or elsewhere. For now, it is up to our calling code to provide the appropriate variables to the template depending on the context.

All user-configurable settings have a definition, if not also a default value. For single-sourcing purposes, these are defined in a YAML format called CFGYML — a configuration-file modeling language.

The file is at ./specs/data/config-def.yml. It is used to establish the literal default settings carried by the application, and also to document those settings for the user.

This practice lets developers give end users extremely detailed configurations, always well documented.

Similar to but more complicated than CFGYML definition files are SchemaGraphy schema files. This is a partially specified, partially developed, and as-yet-incomplete syntax for designating and constraining YAML documents.

ReleaseHx at this time makes active use of only minimal aspects of these schemas, all of which are contained in the specs/ directory at the root of the gem source.

Each of the YAML formats used by ReleaseHx has its own schema in the repo. The cfgyml-schema.yaml file will eventually be spun off, but the specs/data/rhyml-schema.yaml and specs/data/rhyml-mapping-schema.yaml files will stay here, defining valid formats for the types of files they apply to.

Since SchemaGraphy itself is still unreleased, CFGYML as introduced in this gem offers only a subset of what it will enable down the road.

Once SchemaGraphy is generally available, this gem will call it as a dependency. At that point, a file like specs/data/config-def.yml (CFGYML) will be able to impose a more detailed $schema for any property.

The most powerful function of SchemaGraphy schemas that is now available in ReleaseHx is the ability to instruct how templated fields should be processed at different stages, and also to parse and render them as needed.

Templated-field handling can be established between a combination of (1) CFGYML definition files or SGYML schema files and (2) configuration files to be applied at runtime.

Developers can designate a given property to be type: Template in a schema or definition. This “typing” can be a trigger for downstream parsing/rendering of the template.

Most aspects of SchemaGraphy/SGYML are not yet available in ReleaseHx, but some are worth pointing out.

data types

As of now, the type node of any property in specs/data/config-def.yml is not particularly functional. I do have a whole table of “data types” in SGYML, most of which are extremely self-explanatory and drawn from fairly platonic, cross-language terms.

However, these are entirely unenforced in ReleaseHx — for now, data still has to be type checked explicitly in the Ruby code, and user configs are not validated against any kind of typing system.

schema docs

The schema files do not yet generate complete reference docs for the subject files that they govern. So for instance, you’ll have to read files like specs/data/rhyml-schema.yaml and specs/data/rhyml-mapping-schema.yaml directly to understand the format of RHYML files and how they are mapped to REST response payloads.