Request for Review: Release Notes Fragment-Based Approach

[SandeepaHWP]

I created a pull request to introduce a fragment-based approach for managing release notes.

This issue gives a short overview of the implementation and alternative approaches for consideration.

PR: #5507

The Current Implemented Approach

Each PR adds a small fragment file instead of editing the shared release notes file:

docs/docs/community/release_notes/unreleased/
├── jaclang/
│   ├── feature/
│   │   └── 5503.md
│   └── bugfix/
│       └── 5505.md
├── byllm/
├── jac-client/
├── jac-scale/
├── jac-super/
└── jac-mcp/

At release time, the collect_release_notes.py script merges these fragments and builds the Latest Release section automatically.

Why Markdown and not RST

I chose .md because the codebase already uses Markdown. If fragments were RST, we would need a converter (pandoc or docutils to markdown) in the release pipeline, plus reviewers would see two different syntaxes in the same PR. That is friction with zero upside since mkdocs cannot render RST natively.

Alternative Fragment Layout

Same idea but flatter. Instead of two folders per package (feature/ and bugfix/), we can put the category in the filename:

unreleased/jaclang/
├── 5503.bugfix.md
└── 5505.feature.md

Fewer folders. Category is still clear. Slightly simpler to navigate.

Other Methods to Consider

Method A: PR-description scraping (Kubernetes / Node.js style)

No fragment files at all. Contributors put the release note inside a fenced block in the PR description:

```release-note
Fixed a race condition in the scheduler under high concurrency.
```

A bot scrapes the PR description at release time and aggregates everything. CI checks that the block exists, or accepts a release-note-none label.

• Kubernetes uses Prow with the release-notes tool
• Node.js uses changelog-maker scraping commit trailers

Method B: Conventional commits + auto-generation (release-please / semantic-release style)

Zero extra files, zero extra steps. Commit messages follow a prefix convention like feat:, fix:, chore!:. A bot parses git log between tags and auto-generates the changelog in the release PR.

• release-please (Google) - used across most Google open source
• semantic-release - used across most of npm
• git-cliff - newer Rust-based variant

Request

@asottile Please review the PR and share thoughts on whether the current approach is good, or if one of the alternatives would fit jaseci better.