Skip to content

Add gfm output format for changelog render#3272

Merged
lcawl merged 1 commit into
changelog-render-no-descriptionsfrom
changelog-render-gfm
May 11, 2026
Merged

Add gfm output format for changelog render#3272
lcawl merged 1 commit into
changelog-render-no-descriptionsfrom
changelog-render-gfm

Conversation

@lcawl

@lcawl lcawl commented May 7, 2026

Copy link
Copy Markdown
Contributor

Relates to #3057

AI implementation summary

  • Extended ChangelogFileType Enum - Added Gfm with proper attributes
  • Updated CLI Parsing - Accept --file-type gfm option
  • Created GFM Renderer - Single-file markdown with clean headings
  • Updated Main Dispatcher - Route GFM requests properly
  • Updated Documentation - CLI reference and examples
  • Added Comprehensive Tests - Full test coverage

🚀 Usage

Users can now generate GitHub-ready changelog markdown with:

docs-builder changelog render \
  --input "./bundles/1.10.0.yaml" \
  --file-type gfm \
  --output ./github-release

This produces a clean changelog.md file perfect for copying into GitHub releases.

🔧 Key Improvements Over Standard Markdown

  1. Single File: One changelog.md instead of multiple files
  2. Clean Headings: ### Features and enhancements (no anchor brackets)
  3. GitHub Optimized: Perfect formatting for release notes
  4. Complete Integration: Works with all existing options (--dropdowns, --hide-features, etc.)

The implementation is minimal, follows established patterns, maintains backward compatibility, and includes comprehensive test coverage. Teams can now easily generate clean markdown for their GitHub releases without the docs-builder specific formatting.

Steps for testing

I tested this command as follows:

  1. Refresh docs-builder for local testing per https://github.com/elastic/docs-builder#building-locally:
    ./build.sh clean
    ./build.sh publishbinaries
  2. Run the "changelog render" command against your release bundles. For example, in the kibana repo I ran:
     /path/to/GitHub/docs-builder/.artifacts/publish/docs-builder/release/docs-builder changelog render \
     --input "/path/to/GitHub/kibana/docs/releases/kibana/9.3.0.yaml" \
     --file-type gfm \
     --output ./docs/release-notes/

The command generates a changelog.md file that contains content like this:

## 9.3.0

### Features and enhancements
* Support subqueries in AST. [#241227](https://github.com/elastic/kibana/pull/241227)
* Supports chain controls. [#242909](https://github.com/elastic/kibana/pull/242909) [#238473](https://github.com/elastic/kibana/issues/238473)
* Add subqueries support for walker and visitor. [#241451](https://github.com/elastic/kibana/pull/241451)

Generative AI disclosure

  1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?
  • Yes
  • No
  1. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-2, claude-4-sonnet-thinking

@lcawl lcawl marked this pull request as ready for review May 7, 2026 21:06
@lcawl lcawl requested review from a team as code owners May 7, 2026 21:06
@lcawl lcawl requested a review from Mpdreamz May 7, 2026 21:06
@lcawl lcawl merged commit fdea239 into changelog-render-no-descriptions May 11, 2026
22 checks passed
@lcawl lcawl deleted the changelog-render-gfm branch May 11, 2026 14:17
cotti added a commit that referenced this pull request May 14, 2026
* Add changelog render --dropdowns

* Update changelog render date handling (#3260)

* Fix list indentation

* Improve changelog render for asciidoc (#3262)

* Improve changelog render asciidoc output

* Remove definition lists in favour of subsections

* Update src/services/Elastic.Changelog/Rendering/Asciidoc/DeprecationsAsciidocRenderer.cs

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Move updates from render.md to cmd-render.md

* Refresh cli schema

* Add changelog render --no-descriptions

* Add gfm output format for changelog render (#3272)

* Reconcile render docs

* Refresh cli-schema.json

* Address CodeRabbit review

- Document --no-descriptions in cmd-render.md options and add an
  example entry; the flag existed in the XML doc and cli-schema.json
  but was missing from the user-facing page.
- Drop a trailing backslash from the first shell example so the
  block copy/pastes correctly.
- Strengthen the GFM hide-descriptions test: assert Collector.Errors
  after the second render and check both lines of the multi-line
  description in each pass so multi-line regressions are caught.

Deferred CodeRabbit suggestions (with reason):
- ConfigureAwait(false) on the new GFM awaits: not used anywhere
  else in src/services/Elastic.Changelog/ (zero usages); applying
  it only to the new code would create more drift than it removes.
- Extract helpers from ChangelogGfmRenderer.RenderAsync /
  RenderEntriesByArea to lower branch count: the sibling per-type
  renderers (BreakingChangesMarkdownRenderer, etc.) follow the same
  pattern; refactoring just the new file would be inconsistent and
  is out of scope for this PR.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Felipe Cotti <felipe.cotti@elastic.co>
Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants