Docs
← Back to site

Writing Changelog Entries & Type Badges

2 min readUpdated October 29, 2026

Every changelog entry gets a colored type badge next to its title, helping readers scan a long changelog for the kind of change they care about.

The six entry types#

TypeBadge labelColor
featureNewGreen
improvementImprovedBlue
fixFixedAmber
securitySecurityRed
breakingBreakingPurple
announcementAnnouncementLight blue

Set this from the Entry type dropdown in the Entry details panel while editing an entry (see Setting Up a Product Changelog). New entries default to “New” in the dropdown.

The Changelog screen with the quick entry bar, type filters and entries grouped by month.

How entries are displayed#

On a changelog page, entries are:

  • Sorted newest first, by publish date, not by version number, so entries should generally be published in the order you want them to appear.
  • Grouped under year headings, so a changelog spanning several years is easy to scan by period.
  • Shown with their full content, not a trimmed excerpt, along with the date, version (if set), type badge, and title.

Each entry also gets its own anchor link (#entry-{id}), so you can link directly to one specific release note, clicking an entry’s title jumps to, and highlights, that exact entry.

A product changelog page with entries, version numbers and colored type badges.

On the combined “all products” view#

When viewing the combined changelog across every product (see The Docs Updates Feed), each entry additionally shows a small clickable badge with the product’s name, since entries from different products are mixed together in one list. Clicking it takes you to that product’s own changelog page.

Writing tips#

The meta box itself suggests using the title field for the release headline, something like “Dark mode, keyboard shortcuts & 12 fixes,” rather than a plain version number. The version number has its own field and is displayed separately, so the title is your chance to actually describe what shipped.

Was this helpful?

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only