Release Notes Draft
{{ result.summary.primary }}
{{ result.summary.line }}
{{ badge.label }}
Name the product, release train, or feature set readers will recognize.
The version appears in headings, exports, and optional compare links.
Use the publication or rollout date for the release.
Choose who the finished notes should help first.
Pick where this draft will be published or reviewed.
Mark preview, stable, or yanked releases clearly before publishing.
State the main user-facing outcome before the section list.
Choose the shape of the changes you will paste or import.
{{ sourceHelp }}
{{ fileStatus || 'Drop TXT, MD, or LOG onto the textarea.' }}
Use one note per line. Leave blank only when no user action is needed.
Optional product or repository name for exports.
Optional previous tag for compare links.
Leave blank for portable release notes with no external link.
Optional; each line becomes a Known issues row.
Concise is safest for public notes; technical keeps scope prefixes and stronger change terms.
Turn off to remove common #123 and ABC-123 references from public copy.
Adds placeholder rows for sections that have no source entries.
{{ result.markdown }}
Section Release note Audience signal Release signal Source Copy
No release change rows generated.
{{ row.section }} {{ row.note }} {{ row.audience }} {{ row.signal }} {{ row.source }}
Gate Status Evidence Action Copy
{{ row.gate }} {{ row.status }} {{ row.evidence }} {{ row.action }}
Tags: Devtools, Productivity
Export to PDF Fullscreen
Customize
Advanced
:

Release notes are the readable record of what changed in a product version. They help customers, developers, support staff, and rollout teams decide whether a release matters to them, whether any action is needed, and whether a change should be watched more closely after publication.

A strong release note is not just a commit list. It turns raw change lines into sections that readers can scan quickly, such as highlights, new work, improvements, fixes, security notes, upgrade actions, and known issues. That grouping matters because a reader looking for a migration warning should not have to search through every feature bullet first.

Version numbers and dates also carry meaning. A SemVer-style version can suggest whether a release is expected to be compatible, while an ISO date keeps the publication moment unambiguous across regions. Those signals are useful only when the wording around them is honest about breaking changes, pre-release status, yanked releases, and incomplete upgrade guidance.

Release notes still need judgment. A neat Markdown draft can hide missing context, understate a security fix, or label a breaking change as a normal improvement. Treat the generated draft as a structured review aid before it becomes customer-facing copy or an internal handoff.

Technical Details:

Release-note structure usually combines a release heading, date, short summary, categorized change sections, and any follow-up guidance. The section names make the record more useful than a chronological log because readers can separate new capability from bug fixes, security work, compatibility risk, and current limitations.

Keep a Changelog conventions use named sections such as Added, Changed, Deprecated, Removed, Fixed, and Security. SemVer connects version changes to compatibility intent: patch for compatible fixes, minor for compatible additions or deprecations, and major for backward-incompatible public API changes. Conventional Commit subjects can feed the same review because feat, fix, !, and BREAKING CHANGE: carry common release meaning.

Change lines becoming a release draft, change ledger, readiness review, and export outputs.

Transformation Core:

The generation path starts by normalizing line endings and trimming each source line. Bullets, checkboxes, and numbered-list markers are removed before the text is categorized. The same note is collapsed when it appears more than once under the same section, and the warning area reports the duplicate count.

Source Pattern Detection Generated Handling
Prefix such as added:, fixed:, security:, or upgrade: The prefix is matched against supported release-note aliases. The note is placed in the matching section, such as What is New, Fixes, Security, or Upgrade Notes.
Markdown heading such as ### Fixed The heading sets the section for following plain lines. Later entries inherit that section until another recognized heading appears.
Conventional Commit subject such as feat(exports): add CSV sharing The type maps to a section; a scope may be kept in technical voice. The ledger records the source type, section, reader signal, and release signal.
! before the colon or a BREAKING CHANGE: footer The line is treated as a breaking-change signal. The note moves to Breaking Changes and receives a Major release signal.
Plain source mode Every non-empty line is accepted as a release bullet. Each row becomes a Highlights item unless it also carries a breaking-change phrase.
Upgrade and known-issue fields Each non-empty line is added after the source parser runs. The lines become Upgrade Notes or Known Issues rows and appear in the review tables.

Release Signal Rules:

Release signals are review cues, not proof of compatibility. They point reviewers toward likely versioning and communication work, then the release owner still confirms the real product impact.

Condition Signal Review Meaning
Breaking Changes or Removed rows Major Confirm migration wording, replacement guidance, and public compatibility impact.
What is New or Improvements rows Minor Check that new behavior and changed behavior are described from the reader's point of view.
Fixes or Security rows Patch Confirm the correction is clear and security wording has the right disclosure level.
Upgrade Notes, Known Issues, or Deprecated rows Action needed, Watch item, or Future action Make sure readers know what to do now, what to monitor, or what will change later.
Documentation or Other Notes rows Reference or Review Decide whether the row belongs in public notes or only in an internal handoff.

The readiness checks validate a SemVer-like version shape, an ISO YYYY-MM-DD release date, non-empty change coverage, a reader summary, parser warnings, breaking-change visibility, upgrade notes, security wording, known issues, yanked status, and optional compare-link inputs.

Everyday Use & Decision Guide:

Start with Release title, Version, Release date, and Release summary. The title and version form the top heading, the date appears in the draft when supplied, and the summary gives readers the short answer before they scan section bullets.

Choose Change source format from the shape of the material you already have. Use category prefixes or Markdown sections for prepared release-note notes, Conventional commits or PR titles for commit-style subjects, and plain bullets when the source is already reader-facing but not categorized. TXT, MD, and LOG files up to 512 KB can fill Release changes through the browser file reader.

  • Set Audience to customers when the final wording should favor reader outcomes, developers when scope and technical detail matter, or internal teams when rollout evidence should stay visible.
  • Use Publication format to shape the Markdown as a public draft, GitHub release body, or internal handoff.
  • Mark Release status as pre-release or yanked only when that warning should be visible in the draft and review rows.
  • Add Previous version and Repository URL only when a compare or tag link should be generated.
  • Turn off Keep issue and PR references when public copy should drop common #123 and ABC-123 references.
  • Enable Include empty optional sections for checklist-style review; leave it off when readers should see only populated sections.

Use the warning block as a stop sign before publication. Warnings can mean lines were ignored, uncategorized rows were mapped to Improvements, an ISO date is missing, the summary is blank, a yanked release lacks replacement guidance, or duplicate rows were collapsed.

Check Readiness Review before copying from Release Draft. A row marked Ready means the draft has enough information for that gate, while Review or Blocker points to a specific field or source line to fix first.

Step-by-Step Guide:

Use this flow to turn rough release material into a draft, ledger, review table, and structured JSON payload.

  1. Fill Release title, Version, and Release date. The Release Draft heading should reflect the title and version, and the readiness table should mark Version label, SemVer shape, and Release date as ready when the values are usable.
  2. Set Audience, Publication format, and Release status. Pre-release and yanked choices add status wording and change the review emphasis.
  3. Choose Change source format, then paste lines into Release changes or use Browse TXT. If a file is larger than 512 KB, the page asks for a smaller TXT, MD, or LOG file.
  4. Use Normalize lines when copied notes contain uneven spacing or blank rows. The source text should become one clean change per line before the parser runs.
  5. Add Upgrade or compatibility notes and, when needed, expand Advanced for Known issues, Voice, issue-reference handling, compare-link inputs, and empty-section behavior.
  6. Open Change Ledger to confirm each row's section, audience signal, release signal, and original source. Fix any row that landed in the wrong section before using the draft.
  7. Open Readiness Review. Clear Blocker rows first, then resolve Review rows that affect publication quality.
  8. Copy or download from Release Draft when the warning block and review table match the release owner's intent. Use JSON when another workflow needs the generated state and results.

For Conventional Commit mode, an ignored-line warning usually means one or more lines lacked type(scope): summary shape. Switch to plain bullets or add a valid type prefix before publishing.

Interpreting Results:

Release Draft is the main copy surface. It combines the heading, date, status, summary, generated sections, and optional full-changelog link. The draft is ready to copy only after the warning block and Readiness Review agree with the release intent.

Change Ledger is the audit view for row placement. If a line appears under the wrong section, fix the source prefix, heading, or source mode rather than editing the generated Markdown by hand. The ledger's Release signal helps spot breaking changes, removed features, security notes, upgrade actions, and rows that need reviewer judgment.

Readiness Review does not prove the release is correct. A SemVer-shaped version can still understate a real breaking change, and a draft with no detected breaking row can still need migration guidance. Treat Ready as a field-level check, not a release approval.

Use JSON when you need a structured payload containing the current parameters, summary, Markdown, ledger rows, review rows, warnings, and row statistics. Use CSV or DOCX exports when the ledger or review table needs to move into a human review packet.

Worked Examples:

Customer release with categorized lines

For Atlas Portal 2.4.0 on 2026-05-06, use customer audience, public Markdown, stable status, and category-prefixed changes such as highlight: New account export panel, fixed: Billing status badge no longer stays stale, and security: Invite tokens are redacted. The Release Draft should include sections for Highlights, What is New, Improvements, Fixes, Security, and Upgrade Notes. If the same upgrade note appears in both the source text and upgrade field, Readiness Review adds a duplicate-row review item.

Developer pre-release from commit subjects

For a developer audience, set publication format to GitHub release body, release status to pre-release, and source mode to Conventional commits. Lines such as feat(exports): add scheduled CSV sharing, fix(billing): refresh stale plan badges, and feat(api)!: require export.read scope produce Added, Fixed, and Breaking Changes rows. Change Ledger keeps the source type and scope, while Readiness Review marks breaking changes for migration review.

Troubleshooting an empty draft

If Conventional Commit mode receives plain lines such as Faster dashboard tiles and Billing badge refreshes after checkout, those lines are ignored because they do not match commit-subject syntax. The warning block reports ignored lines, and Change coverage can become a Blocker. Switch Change source format to plain bullets, or rewrite the lines as perf(dashboard): load tiles faster and fix(billing): refresh badge after checkout.

FAQ:

Can this replace release-owner review?

No. It builds a structured draft, ledger, warnings, and readiness rows, but a release owner still needs to confirm customer impact, compatibility, security wording, and rollout guidance.

Why did my uncategorized line become an improvement?

In category-prefix mode, a non-empty line without a recognized prefix or heading is accepted and mapped to Improvements. Add prefixes such as added:, fixed:, security:, or upgrade: for stricter placement.

Why is the SemVer check marked for review?

The version field should look like 2.4.0, v2.4.0, or a valid pre-release or build variant. A blank or non-SemVer label still generates a draft, but the review table asks you to confirm the public version before publishing.

What happens when issue references are turned off?

Common references such as #123 and ABC-123 are removed from generated notes when the issue-reference switch is off. Keep the switch on for internal handoffs or technical drafts where those references help reviewers trace changes.

How are TXT, MD, or LOG files handled?

The file reader fills Release changes in the browser, and files above 512 KB are rejected. After loading, the same parser handles the content as pasted text for the selected source format.

Glossary:

Release notes
Reader-facing notes that explain notable changes in a product version.
SemVer
Semantic Versioning, a versioning convention that uses major, minor, and patch numbers to communicate compatibility intent.
Conventional Commit
A commit-subject format such as feat(scope): summary or fix(scope): summary that can be parsed into release meaning.
Breaking change
A change that can require users or integrators to adjust their usage before or during upgrade.
Compare link
A link built from repository and version fields so reviewers can inspect changes between tags.
Readiness Review
The generated table of release gates, statuses, evidence, and suggested actions before publication.

References: