issue_hierarchy_support.md

Feature: Issue Hierarchy Support

Purpose

Represent issue → sub-issue relationships directly in release notes, aggregating linked sub-issues and their pull requests under hierarchical parents. Gives stakeholders a structured view of larger deliverables.

How It Works

• Enabled via input hierarchy: true (default: false). When disabled, all issues render flat.
• Parent issues are detected; sub-issues (and nested hierarchy issues) are fetched and ordered by level. Levels indent with two spaces per depth; nested items use list markers (-).
• When the parent hierarchy issue is open:
  • Leaf sub-issues: only closed ones with a change increment are rendered; open ones and those closed or delivered in a previous release are ignored.
  • Nested sub-hierarchy children: filtered by change increment only — an open child that aggregates PRs from deeper levels is still rendered.
• When the parent hierarchy issue is closed:
  • All children (sub-issues and nested sub-hierarchy children) are rendered. Open children are prefixed with the open-hierarchy-sub-issue-icon (default 🟡) to signal incomplete work.
  • Set open-hierarchy-sub-issue-icon to an empty string to disable the highlighting.
• Each hierarchy issue line can expand with its own extracted release notes block if present (prefixed with _Release Notes_: heading within the item block).

Configuration

- name: Generate Release Notes
  id: release_notes_scrapper
  uses: AbsaOSS/generate-release-notes@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tag-name: "v1.6.0"
    hierarchy: true
    chapters: |
      - {"title": "New Features 🎉", "label": "feature"}

Optional inputs related to hierarchy:

Input	Default	Description
open-hierarchy-sub-issue-icon	🟡	Icon prepended to open sub-issues and open sub-hierarchy issues rendered under a closed hierarchy parent. Set to an empty string to disable highlighting.

Example Result

### New Features 🎉
- Epic: _Make Login Service releasable under new Maven central repository_ #140
  - Updated `sbt.version` to `1.11.5` for release.
  - Updated Developers
  - Updated `sbt-ci-release` to `1.11.2`
  - Updated `scala213 = "2.13.13"`
  - Feature: _Add user MFA enrollment flow_ #123 developed by @alice in #124
    - Add user MFA enrollment flow
  - 🟡 Feature: _Add OAuth2 login_ #125  ← open sub-issue under closed Epic

(1st four indented bullets under Epic line represent the extracted release notes from the parent hierarchy issue's body.)

{progress} Format Token

The {progress} token is available in row-format-hierarchy-issue. It renders the sub-issue completion count for each hierarchy node as "X/Y done", where X and Y count direct children only — no recursive aggregation.

• Counts both SubIssueRecord and nested HierarchyIssueRecord direct children.
• Each hierarchy level computes its own count independently when to_chapter_row() recurses.
• Leaf nodes (zero direct sub-issues) return an empty string; the token is suppressed, producing no extra whitespace.

Example

Configuration required to enable {progress} in hierarchy rows:

row-format-hierarchy-issue: "{type}: _{title}_ {number} {progress}"

Resulting output (hierarchy issues only — sub-issue rows use row-format-issue and do not carry {progress}):

- Epic: _Make Login Service releasable_ #140 1/2 done
  - Feature: _Add user MFA enrollment flow_ #123 1/1 done
    - Add user MFA enrollment flow
  - Feature: _Add OAuth2 login_ #125 0/1 done

Related Features

• Custom Row Formats – controls hierarchy line rendering.
• Service Chapters – flags missing change increments if hierarchy parents lack qualifying sub-issues.
• Duplicity Handling – duplicate hierarchy items can be icon-prefixed if allowed.
• Super Chapters – hierarchy records split across super chapters when descendants carry different super-chapter labels.

← Back to Feature Tutorials