Changelogs and Updates

When you publish your plugin in the Plugin Store, you will be able to specify a path to your plugin’s changelog within the repository.

If this is set to a valid changelog path, the Plugin Store will re-download your changelog on each release. Those release notes will then be displayed on its Plugin Store page, as well as the Utilities → Updates screen of any project it is installed in.

Refer to Craft’s own changelog (opens new window) as an example of syntax and best practices.

# Setting Up a Changelog

Create a CHANGELOG.md file at the root of your plugin’s repo, where you can start documenting release notes for your plugin. Use something like this as a starting point:

# Release Notes for <Plugin Name>

Within the changelog, releases must be listed in descending order (newest-to-oldest). When displaying available plugin updates, the Plugin Store will stop parsing a plugin’s changelog as soon as it finds a version that is older than or equal to the user’s installed version.

# Version Headings

Version headings in your changelog must follow this format:

## X.Y.Z - YYYY-MM-DD

There’s a little wiggle room on that:

  • Other text can come before the version number, like the plugin’s name.
  • A 4th version number is allowed (e.g. 1.2.3.4).
  • Prerelease versions are allowed (e.g. 1.0.0-alpha.1).
  • The version can start with v (e.g. v1.2.3).
  • The version can be hyperlinked (e.g. [2.0.0](https://domain.com/blog/whats-new-in-v2)).
  • Dates can use dots as separators, rather than hyphens (e.g. 2024.04.18).

Any level-two headers (##) that don’t follow this format will be ignored, as will any content that follows them (until the next valid level-two heading).

# Release Notes

All content that follows a version heading (up to the next version heading) will be treated as the release notes for the update.

When writing release notes, we recommend that you follow the guidelines at keepachangelog.com (opens new window), but all forms of GitHub Flavored Markdown (opens new window) are allowed. The only thing that is not allowed is actual HTML—raw markup will be escaped.

# Alerts

You can include notes and warnings in your release notes using GitHub’s alert syntax (opens new window):

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

These alerts will each be styled appropriately within the plugin’s changelog in the Plugin Store and within the Updates utility. Updates which contain alerts will automatically be expanded in the Updates utility.

If you have any reference-style links in your release notes, you will need to define the URLs before the following version heading:

## 2.0.1 - 2017-02-01
### Fixed issue [#123]

[#123]: https://github.com/pixelandtonic/foo/issues/123

## 2.0.0 - 2017-01-31
### Added
- New [superFoo] config setting

[superFoo]: https://docs.my-plugin.tld/config#superFoo

Relative URLs will not work. Your changelog may appear in multiple contexts—so even if a link resolves when viewing the changelog on GitHub, it may not work from a Craft installation or the Plugin Store!

# Critical Updates

If an update contains a fix for a critical security vulnerability or other dangerous bug, you can alert your users about it by adding [CRITICAL] to the end of the version heading:

## 2.0.1 - 2017-01-21 [CRITICAL]
### Fixed
- Reverted change to `$potus` due to security vulnerabilities

When Craft finds out that a critical update is available, it will post a message about it to the top of all control panel pages, and give the update special attention on the Utilities → Updates page.