Skip to content

DocOps/releasehx-demo

BranchesTags

Repository files navigation

ReleaseHx Demo Repository

Demonstration assets, testing suite, and development workspace for the ReleaseHx release note/changelog generation utility.

Table of Contents

Overview

This repository serves multiple purposes:

  • Demonstration workspace with sample configurations and mock API data

  • Integration testing environment for ReleaseHx features and API clients

  • Development testing harness for contributors working on ReleaseHx core

  • Reference implementation showing real-world usage patterns

The repo contains realistic mock data from Jira, GitHub Issues, and GitLab Issues APIs, along with corresponding configuration files that demonstrate various output formats and customization approaches.

Quickstart

For end users wishing to test ReleaseHx using sample data, this Quickstart section provides basic commands to generate release notes in different formats.

Tip
 If you just want to see the various sample output generated by the releasehx-demo source content, see skip to the Generated Artifacts listing.

Use this guide to get going with the tool as quickly as possible given your existing setup.

Prerequisites

ReleaseHx relies on a couple of existing technologies, in addition to your cloud-based issues platform. To use this demo repo, you’ll need:

Git

Git CLI or a basic Git GUI, or a virtualized Git environment in the cloud.

Ruby 3.x

If you do not have a Ruby 3.x environment available, see the “Non-Ruby Users Setup” section of the ReleaseHx documentation. A Docker image is available.

Clone the Demo Repo

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

Ruby Installation

This repository has a Gemfile, so you can sync with the latest ReleaseHx gem binary.

Install ReleaseHx
bundle install

Basic Demo Commands

These commands demonstrate core ReleaseHx functionality using mock data.

Generate Markdown release notes from Jira mock data to default path
bundle exec rhx 1.1.0 \
  --config _configs/jira-customfield.yml \
  --api-data _payloads/jira-customfield-note-1.1.0.json \
  --md
Generate AsciiDoc with GitHub data to specified path
bundle exec rhx 1.1.0 \
  --config _configs/github-basic.yml \
  --api-data _payloads/github-label-tags-1.1.0.json \
  --adoc __output/drafts/github-basic-1.1.0.adoc --force
Tip
 For more options, use bundle exec rhx --help and bundle exec rhx --man, or see the ReleaseHx documentation.

Keep Demo Repo in Sync

By default, generated paths are not tracked in Git due to the .gitignore file.

Note
 The files generated by the default demo content and configs are tracked in the generated/<version> branches, where <version> is either latest or a valid ReleaseHx version code.

This means you can keep the files in this repo in sync with any upstream changes, even as you play with generating output, all without worrying about Git conflicts.

Fetch upstream files
git pull origin main
In case of conflict

  1. Stash your changes.

    git stash

  2. Pull upstream changes.

    git pull origin main

  3. Reapply your changes.

    git stash pop

The ReleaseHx documentation is the authoritative source for all configuration options and features.

Repository Structure

These key paths constitute the supported elements of this demonstrative codebase. See the complete Path Tree for default output paths, which are not tracked in Git but created when releasehx is executed with various options.

All of the built-in demo files are mapped in combination with descriptions in specs/files-matrix.yml.

App Configuration Files (_configs/`)

Sample ReleaseHx application config files demonstrating different platform integrations and output formats.

To activate a specific configuration, use the --config _configs/<filename>.yml CLI option.

Mock API Data (_payloads/)

JSON files simulating real API responses from different issue management systems.

Generated Artifacts

Parsing the mock data with the sample configurations produces various output files in different formats.

These files are not tracked if you generate them locally, but we do maintain version-specific frozen snapshots in artifacts/.

Demo Output (__output/)

User-facing demo output for inspection and experimentation.

  • __output/drafts/ - YAML, Markdown, AsciiDoc drafts

  • __output/publish/ - HTML, PDF enriched outputs

    Examples: github-basic.md, jira-customfield.md, gitlab-basic.md

Test Output (__tests/)

Automated test results (for contributors).

  • __tests/cli/ - CLI workflow test outputs

  • __tests/readme/ - README command test outputs

  • __tests/dynamic/ - Matrix generation test outputs

  • __tests/validation/ - Content quality validation results

Artifacts (artifacts/)

Version-specific frozen snapshots for showcase.

Note
 On main branch, artifacts/ is gitignored. It’s committed only to generated/* branches for showcase purposes.

  • artifacts/rhx-0.1/ - Files generated by ReleaseHx 0.1.x (flat structure)

  • artifacts/rhx-latest/ - Current version showcase (flat structure)

    See generated/latest branch and generated/0.1 branch for comprehensive output examples.

Custom Templates and Mappings

Default files can be overridden by placing altered versions of the ReleaseHx default version with a file of the same name in the designated custom directory.

Because this behavior is supported by default, these directories are named with a trailing underscore (_) to avoid accidental activation.

_templates_/

Custom Liquid templates for overriding default output in Markdown, AsciiDoc, HTML, YAML, and formats. Includes minor examples to demonstrate modification of partials.

Important
 To activate, either alter the base path from _templates_/ to _templates/ (remove the trailing _) or specify the path via the config.paths.templates_dir setting in the application config.
_mappings_/

API-to-RHYML field mapping overrides. Includes customized examples to demonstrate adaptation based on particular use of issue structure and how it expresses in the API response payload.

Important
 To activate, either alter the base path from _mappings_/ to _mappings/ (remove the trailing _) or specify the path via the config.paths.mappings_dir setting or argue the path using the --mapping PATH option in the CLI.
_apis_/

Custom API client overrides or extensions. Includes minor examples to demonstrate modification of API client behavior (or entirely new clients for entirely different issue-tracker APIs).

Important
 To activate, either alter the base path from _apis_/ to _apis/ (remove the trailing _) or specify the path via the config.paths.custom_apis_dir.
Note
 The releasehx-demo repo does not ship with alternate API files at this time.

Path Tree

.
├── _configs/                  # Sample ReleaseHx configurations
├── _payloads/                 # Mock API response JSON files (tracked)
├── _templates_/               # Custom template overrides (inactive)
├── _apis_/                    # Custom API client overrides (inactive)
├── _mappings_/                # Custom API mapping overrides (inactive)
│   ├── api-test/
│   ├── checkbox-tags/
│   ├── customfield-note/
│   ├── description-note/
│   ├── generic/
│   ├── label-tags/
│   └── legacy-labels/
├── scripts/                   # Generation and utility scripts
│   ├── dynamic-gen.rb         # Dynamic artifact generation script
│   └── validate-content.rb    # Content quality validation
├── specs/
│   └── data/
│       └── files-matrix.yml   # Combinations of demo files
├── drafts/                    # Default ReleaseHx output (gitignored)
├── __output/                  # Demo output (gitignored)
│   ├── drafts/                # YAML, Markdown, AsciiDoc
│   └── publish/               # HTML, PDF
├── __tests/                   # Test output (gitignored)
│   ├── cli/                   # CLI workflow test results
│   ├── readme/                # README command test results
│   │   ├── drafts/
│   │   └── publish/
│   ├── dynamic/               # Matrix generation test results
│   │   ├── github-basic/
│   │   ├── jira-description/
│   │   └── ...
│   └── validation/            # Content validation results
└── artifacts/                 # Version-specific snapshots (gitignored)
    ├── rhx-0.1/               # ReleaseHx 0.1.x generated files
    └── rhx-latest/            # Current version showcase

Directory Standards

Source directories (tracked)
_configs/

Sample ReleaseHx application configurations

_payloads/

Mock API response data for testing

scripts/

Generation and utility scripts

templates/, apis/, mappings/

Custom override examples (inactive by default)

Output directories (gitignored)
__output/

Demo output from user-facing commands. This is where README examples generate files for users to inspect.

  • __output/drafts/ - YAML, Markdown, AsciiDoc draft files

  • __output/publish/ - HTML, PDF enriched files

__tests/

Automated test execution results. Organized by test type for clarity.

  • __tests/cli/ - CLI workflow test outputs

  • __tests/readme/ - README command test outputs (preserves drafts/ and publish/ subdirs)

  • __tests/dynamic/ - Matrix generation outputs (subdivided by config combo)

  • __tests/validation/ - Content quality validation results

artifacts/

Version-specific frozen snapshots for showcase.

Note
 Gitignored on main branch, committed only to generated/* branches.

  • artifacts/rhx-0.1/ - Files generated by ReleaseHx 0.1.x (flat structure)

  • artifacts/rhx-latest/ - Current version showcase (flat structure)

These directory names follow ReleaseHx default path conventions as defined in ../releasehx/specs/data/config-def.yml.

Note

The artifacts/ directory is gitignored on main but committed to generated/* branches. When you run rake generate_release, artifacts are:

  1. Generated to artifacts/rhx-0.1/ on main

  2. Committed to an orphan generated/0.1 branch

  3. Cleaned from main after branch creation

This keeps main clean while showcasing output on dedicated branches.

Development

For contributors working on ReleaseHx core:

Development Setup Requirements

Important
 This demo repository requires the ReleaseHx repository to be present at ../releasehx for local development and testing. This is used by dev-install.sh to build and install the latest ReleaseHx version.
Install development dependencies
./dev-install.sh

Demo Infrastructure Logic

The subdirectories in this repo were named carefully, if not intuitively.

Directories beginning with an underscore () contain source matter or generated matter for the demos in this repo. They represent paths you might use in an _application of ReleaseHx in your own repo.

Dirctories beginning with double underscores (__) are generated using the source files. These files are committed only to the generated branch.

Directories beginning with a dot (.) contain files pertaining to APIs, tools, or libraries related to development but not use of this repo.

The directory mappings/ is so-named (with trailing ) because ReleaseHx looks for a _mappings/ path, for custom API mapping files. You won’t want to use these unless you _do want to use them.

Directories with neither prefix (ex: scripts/, specs, pertain to the function and upkeep of the demo codebase itself)

Testing & Development Infrastructure

Rakefile

Rake-based test runner and development task automation

dev-install.sh

Development setup script for local gem installation

scripts/dynamic-gen.rb

Dynamic artifact generation script driven by specs/files-matrix.yml for creating demo output across all supported formats and configurations

Rake Tasks

The following commands are available for testing, development, and artifact generation.

Testing Tasks

Run all tests
rake test
Run API client tests
rake api_test
Run CLI workflow tests
rake cli_test
Validate YAML files
rake yaml_test

Development Tasks

Clean generated files
rake clean
Setup demo environment
rake setup
Generate all sample output artifacts
rake generate_artifacts
Tasks from docopslab-dev
bundle exec rake --tasks | grep labdev:

+ This releasehx-demo repo is supported by tasks from the DocOps Lab Devtool (`docopslab-dev).

Testing Methodology

Consolidated Test Structure

The testing approach focuses on end-to-end validation using the installed ReleaseHx gem:

CLI Workflow Tests (via Rake)

  • End-to-end workflow testing

  • Command-line option validation

  • Output file verification

Dynamic Generation Tests

  • Matrix-based testing of all config-payload combinations

  • Multi-format output validation (YAML, Markdown, AsciiDoc, HTML, PDF)

  • Comprehensive error reporting and summaries

README Command Validation

  • Automated testing of all documented commands

  • Ensures documentation stays accurate and working

Mock Data Strategy

The repository uses realistic mock API responses rather than live API calls for:

Reproducible testing

Consistent results across environments

Offline development

No network dependencies for core testing

Edge case coverage

Specific scenarios that might be rare in production

Security

No real API credentials required

API Client Testing

The API-CLIENT-TESTING-PLAN.adoc document outlines the comprehensive strategy for testing REST API integrations across different platforms, including authentication, error handling, and data transformation scenarios.

Config-Payload Coordination

Overview

Each configuration file in _configs/` is designed to work with specific payload files in _payloads/. The configurations define how to extract and process data from their corresponding API response structures.

Critical Alignment Requirements

Types Configuration

The types: section must match the type values in the payload data.

  • For GitHub: Labels like bug, feature, enhancement must be defined in config

  • For Jira: Component names or custom field values must match config definitions

  • For GitLab: Label values must correspond to configured type definitions

Parts Configuration

The parts: section defines component groupings and must align with payload structure.

  • label_prefix settings (e.g., part:) must match label naming in payload

  • Part names (e.g., api, ui, webui) must exist in the actual issue data

  • Mapping extractors must be configured to find parts in the correct payload fields

Tags Configuration

Tag extraction depends on proper _include/_exclude lists and tag definitions that match payload labels.

Sort Configuration

changelog.sort and notes.sort arrays must reference defined types, parts, and tags using the correct syntax (e.g., type:grouping1, part:grouping2).

Standardized Testing Commands

All testing commands use organized output directories:

Demo Output (__output/)

User-facing demo commands output to output/drafts/ and output/publish/. These are the commands shown in examples that users can run to experiment.

Test Output (__tests/)

Automated tests capture outputs to tests/ (organized by test type). The test harness executes demo commands and copies results to tests/ for validation.

Artifacts (artifacts/)

Frozen snapshots for version-specific showcases (not for direct use).

Config-Payload Verification Commands

GitHub Integration
# Basic test with aligned config and payload
bundle exec rhx 1.0.0 \
  --config _configs/github-basic.yml \
  --api-data _payloads/github-1.0.0-issues.json \
  --md __output/drafts/github-basic.md --force

# Validation check
bundle exec rhx 1.0.0 \
  --config _configs/github-basic.yml \
  --api-data _payloads/github-1.0.0-issues.json \
  --check

# RHYML generation
bundle exec rhx 1.0.0 \
  --config _configs/github-basic.yml \
  --api-data _payloads/github-1.0.0-issues.json \
  --yaml __output/drafts/github-basic.yml --force
Jira Integration
# Custom field extraction test
bundle exec rhx 1.1.0 \
  --config _configs/jira-customfield.yml \
  --api-data _payloads/jira-customfield-note-1.1.0.json \
  --md __output/drafts/jira-customfield.md --force

# Validation check
bundle exec rhx 1.1.0 \
  --config _configs/jira-customfield.yml \
  --api-data _payloads/jira-customfield-note-1.1.0.json \
  --check
GitLab Integration
# Label-based processing test
bundle exec rhx 1.1.0 \
  --config _configs/gitlab-label-tags.yml \
  --api-data _payloads/gitlab-label-tags-1.1.0.json \
  --md __output/drafts/gitlab-basic.md --force

# Validation check
bundle exec rhx 1.1.0 \
  --config _configs/gitlab-label-tags.yml \
  --api-data _payloads/gitlab-label-tags-1.1.0.json \
  --check

Troubleshooting Config-Payload Mismatches

Common issues and their resolution:

Empty Sections in Output

Check that types, parts, and tags in config match the actual labels/values in the payload data.

Type Extraction Returning nil

Verify that type extraction logic in mapping file aligns with payload structure and config definitions.

Parts Not Grouping Correctly

Ensure label_prefix in config matches the prefix used in payload labels (e.g., part:api requires label_prefix: 'part:').

Sort Configuration Errors

Verify that changelog.sort and notes.sort reference valid type, part, and tag configurations using proper syntax.

Verified Config-Payload Pairs

The following configurations have been verified to work correctly with their corresponding payloads:

Config File Payload File Version Status

github-basic.yml

github-1.0.0-issues.json

1.0.0

Types: bug, feature
Parts: api, ui with part: prefix
Sort: part:grouping1 (changelog), type:grouping1 (notes)

jira-customfield.yml

jira-customfield-note-1.1.0.json

1.1.0

Types: from component names
Parts: webui, api via components
Custom field: customfield_10039 for notes (ADF format)

gitlab-label-tags.yml

gitlab-label-tags-1.1.0.json

1.1.0

Types: bug, enhancement from labels
Parts: collaboration, search, database, ai, configuration
Tags: highlighted, breaking, removal, etc.

jira-description.yml

jira-description-note-1.1.0.json

1.1.0

Note extraction from description field (ADF format)
Section extraction by heading ("Release Note")
Full ADF → Markdown → AsciiDoc pipeline

Config Modification Guidelines

When adapting configurations for your own use:

Types Alignment

Ensure your issue tracking labels/fields match the types: definitions in your config.

Parts Structure

Configure parts.label_prefix to match your labeling convention (e.g., component:, area:, part:).

Sort Requirements

changelog.sort needs at least one grouping field (part:grouping1, type:grouping1, etc.) to avoid empty output.

ADF (Atlassian Document Format) Testing

The demo repository includes comprehensive examples for testing Jira Cloud API with ADF format.

ADF Payloads

  • jira-description-note-1.1.0.json - Description field with ADF, section extraction by heading

  • jira-customfield-note-1.1.0.json - Custom field with full ADF content conversion

ADF Configurations

  • jira-description.yml - Configured with sources.note_heading: "Release Note" for section extraction

  • jira-customfield.yml - Configured with sources.note_custom_field: customfield_10039 for full conversion

Testing ADF Workflows
Description-based with section extraction
bundle exec rhx 1.1.0 \
  --config _configs/jira-description.yml \
  --api-data _payloads/jira-description-note-1.1.0.json \
  --mapping _mappings_/description-note/jira.yaml \
  --yaml __output/drafts/jira-description-1.1.0.yml --force
Custom field-based with full conversion
bundle exec rhx 1.1.0 \
  --config _configs/jira-customfield.yml \
  --api-data _payloads/jira-customfield-note-1.1.0.json \
  --mapping _mappings_/customfield-note/jira.yaml \
  --yaml __output/drafts/jira-customfield-1.1.0.yml --force
Generate AsciiDoc from ADF (full pipeline)
bundle exec rhx 1.1.0 \
  --config _configs/jira-description.yml \
  --api-data _payloads/jira-description-note-1.1.0.json \
  --mapping _mappings_/description-note/jira.yaml \
  --adoc __output/drafts/jira-description-1.1.0.adoc --force
Supported ADF Elements

The ADF payloads include examples of:

  • Text marks: bold, italic, code, links, strikethrough

  • Lists: bullet lists, ordered lists, nested lists

  • Code blocks with language syntax

  • Blockquotes

  • Panels (converted to AsciiDoc admonitions)

  • Tables

  • Hard breaks

All ADF content is automatically detected and converted to Markdown, then optionally to AsciiDoc, HTML, or PDF.

Environment Setup for Jira v3

To test with live Jira v3 API (instead of mock data):

export JIRA_API_VERSION=3
export JIRA_HOST="https://your-domain.atlassian.net"
export JIRA_PROJECT="PROJ"
export JIRA_USERNAME="your.email@company.com"
export JIRA_API_TOKEN="your_api_token"

Then use --api instead of --api-data to fetch live issues.

Mapping Updates

If changing data structure, update corresponding mapping files in _mappings/ to extract from correct API response fields.

Alternate Mappings for Different API Structures

This repository includes alternate mapping configurations for common scenarios where the default API mappings don’t match your issue management setup.

Legacy Label-based GitHub Mapping
Location

mappings/legacy-labels/github.yaml

Use Case

GitHub repositories that don’t use native issue types, instead using labels like type:bug, type:feature, kind:enhancement.

Key Differences from Default:

  • Extracts types from labels[].name instead of issue_type.name

  • Includes Ruby logic to handle label prefixes (type:, kind:, etc.)

  • Compatible with older GitHub Issue configurations

    Required Config Changes
    types:
  label_prefix: 'type:'  # or 'kind:', 'category:', etc.
  bug:
    slug: bug            # matches the part after 'type:'
    text: Bug Fix
    Testing Command
    bundle exec rhx 1.0.0 \
  --config _configs/github-legacy-labels.yml \
  --mapping _mappings_/legacy-labels/github.yaml \
  --api-data _payloads/github-label-types-1.0.0.json \
  --md __output/drafts/github-legacy.md --force
When to Use Alternate Mappings

Consider alternate mappings when:

API structure mismatch

Your API responses don’t match the expected field structure in default mappings.

Legacy label systems

You use label-based categorization instead of native type/component fields.

Custom field extraction

You need to extract data from non-standard API response locations.

Multi-platform consistency

You want consistent field extraction across different issue tracking platforms.

Creating Custom Mappings

  1. Copy a default mapping from the main ReleaseHx installation.

  2. Modify field paths to match your API structure

  3. Update Ruby extraction logic for complex transformations

  4. Test with representative payloads to verify data extraction

  5. Adjust application config for any label prefixes or field changes

Release Procedure

This repository uses an artifacts-only branch workflow to showcase generated output without cluttering the main branch.

Branch Strategy

Branch names (generated/*)

  • generated/latest - Always contains most recent ReleaseHx version output

  • generated/n.n - Version-specific snapshots (e.g., generated/0.1)

  • Purpose: Orphan branches (no shared history with main)

  • Browse at: generated/latest | generated/0.1

Directory structure on branches

  • artifacts/rhx-0.1/ - All generated files in flat structure

  • README.adoc - Minimal branch documentation

  • .gitignore - Tracks artifacts/ (opposite of main branch)

How .gitignore-generated Works

The .gitignore-generated file on main creates the .gitignore for generated/* branches:

On main branch

  • File .gitignore-generated defines what to track on generated/* branches

  • Specifies: track !artifacts/, ignore source files

During rake generate_release

  • Reads .gitignore-generated content

  • Creates orphan branch generated/0.1

  • Writes content to .gitignore on new branch

  • Result: artifacts/ tracked on generated/* (but gitignored on main)

This inversion is necessary: * Main: artifacts/ gitignored (it’s temporary/generated) * Generated branches: artifacts/ tracked (it’s the whole point)

Release Steps

Prerequisites

  1. Verify: bundle exec rhx --version matches release version

  2. Ensure working directory is clean (commit or stash changes)

  3. Run: bundle exec rake test (all passing)

  4. Commit all changes to main branch (squash to single "Initial commit" if first release)

Create release
# Generate artifacts and create version-specific branch
bundle exec rake generate_release

# The task will create the orphan branch but may fail during git add.
# If it fails, complete manually:
git checkout generated/0.1
git add -f artifacts/ README.adoc .gitignore
git commit -m "Release artifacts for ReleaseHx Demo 0.1 (using ReleaseHx 0.1.2)"

# Return to main and create latest branch alias
git checkout main
git branch -D generated/latest  # Delete if exists
git branch generated/latest generated/0.1

# Tag the release on main
git tag -a v0.1.2-demo -m "ReleaseHx Demo 0.1 - Demonstrates ReleaseHx 0.1.2 capabilities"

These tasks: . Validate version alignment . Generate all artifacts to artifacts/rhx-0.1/ and artifacts/rhx-latest/ . Create orphan branch generated/0.1 with only artifacts + minimal README . Note: The .gitignore on generated branches ignores README.adoc by default, requiring git add -f

Verification

  1. Browse branches on GitHub: generated/latest and generated/0.1

  2. Check flat file structure: github-basic-1.0.0.yaml, jira-customfield-1.1.0.html, etc.

  3. Verify 130+ files per version in artifacts/rhx-0.1/ and artifacts/rhx-latest/

  4. Verify tag: git tag -l | grep demo

Troubleshooting

Version mismatch

Check Gemfile, run bundle install, verify bundle exec rhx --version

Working directory not clean

Commit changes (git commit -am "…​") or stash (git stash) before running release tasks

Branch creation fails during git add

The .gitignore on generated branches may prevent README.adoc from being added. Complete manually with git add -f artifacts/ README.adoc .gitignore then commit.

Branch already exists

Task auto-deletes with git branch -D. If fails, delete manually and retry.

HTML/PDF missing

Some combos in specs/data/files-matrix.yml intentionally skip formats. Check matrix file for format specifications.

Known Limitations

The ReleaseHx Demo repo is still in its infancy, and it has some shortcomings:

  • Mock data does not reflect all real-world API response variations.

  • Some advanced features require live API testing (documented separately).

  • Template and mapping customizations are examples and will need adaptation for specific use cases.

About

Demo configs and data for ReleaseHx tooling

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages