docs: incremental release notes automation via PR description fragments

[Annaxs]

Summary

Release notes are currently compiled manually at release time, requiring a committer to categorise and summarise all merged PRs after the fact. This is time-consuming and produces release notes written by someone other than the PR author, when context about the change is no longer fresh.

Proposed approach

Adopt an incremental model where release note content is contributed by the PR author at merge time, then compiled automatically at release time.

1. PR template change (apache/pulsar)

Add a ### Release notes section to .github/PULL_REQUEST_TEMPLATE.md. Authors fill this in when their change requires operator attention, a notable behaviour change, or upgrade considerations. Example:

### Release notes

#### Changed default value of `managedLedgerMaxEntriesPerLedger`
The default has changed from 50000 to 10000. Clusters upgrading from < 3.x should review this setting before upgrading.

PRs that contain this section are labelled release-notes at review time.

2. Compilation script (apache/pulsar-site)

A Python + uv script collects all release-notes-labelled PRs merged since the last release, extracts the ### Release notes section from each PR description, normalises markdown heading levels (e.g. #### → ##, ##### → ###), and compiles them into a structured release notes document.

Script header (uv inline dependencies, no install required):

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests>=2.31.0",
#     "PyGithub>=2.1.1",
# ]
# ///

3. Upgrade considerations flag (optional)

A PR author can add upgrade-attention: true as a marker within their release note block. The script uses this to auto-populate a dedicated Upgrade Considerations section at the top of the release notes.

Why this approach

• Release note content is written by the author when context is fresh
• No new tooling for contributors — just a markdown section in the PR description
• Compiler script is a standalone Python file, runnable by any release manager with uv installed
• Label-based filtering is reliable (GitHub text search is not)
• Heading level normalisation means authors don't need to think about the final document structure

Related

• Discussed on the Apache Pulsar Slack #dev channel, May 2026
• Lari Hotari noted the Gradle incremental release notes model as inspiration
• Release process docs: https://pulsar.apache.org/contribute/release-process/#update-the-document

[Annaxs]

@lhotari — wanted to follow up on this. Would love to hear your thoughts on whether this direction makes sense for the project before moving forward with implementation. Happy to adjust the approach based on your feedback.