Documentation/API documentation/Changelog

Tracked in Phabricator
Task T405573

Changelog is a record of all notable changes made to a project. This page describes a common structure and format for Wikimedia API changelogs. It's based on recommendations available on Keep a Changelog (under MIT license) and in the Common Changelog style guide (under MIT license).

General information

Location

The Wikimedia API documentation guidelines recommend including the changelog in the regular API documentation structure. The correct location for the changelog is alongside contact and maintenance content, next to contribution guidelines and instructions on reporting issues.

Format support

If you are storing and writing a changelog in a Markdown file, use the Common Changelog style guide. You can then use the Hallmark linter to generate content for a new changelog entry.

If you are writing a changelog in a different format, you can adapt the Common Changelog guide to that format or use the instructions below.

Changelogs should be written, or at least edited and verified, by humans. Only API maintainers, in communication with their teams and API users, can determine which changes to include and highlight in different parts of the changelog.

Content overview

The changelog contains:

• information about noteworthy changes
• information about breaking changes and how to deal with them (in the notice, see Changelog entry)
• links from changes to further information, typically commits and tickets

The changelog doesn't contain:

• unedited copy of git log or commit history
• changes within a single release that cancel each other (for example reverted commits)

Full content and structure

The changelog page or file contains:

• title of the page - typically "Changelog", or "<API name> changelog"
• one or more changelog entries, each entry representing an API release or update

Changelog entry

Each changelog entry represents an API release, update, or a group of updates, and includes:

• a heading that specifies the API version (if used) and a date (ISO 8601 format) indicating when the release or update came into effect
• (optional) a notice with extra notes or links to resources related to the release, for example an upgrade guide. You can also use the notice to provide details about change availability or versioning, especially in the absence of an established API versioning scheme. This might be useful for API releases that are dated but not versioned, or for versions tied to MediaWiki releases.
• one or more change groups

Change group

Each change group includes:

• heading, this can be (in order):
  • Changed
  • Added
  • Removed
  • Fixed
• list of changes in a given category (represented by the heading)

Change

Each change:

• is self-contained and requires no extra context
• is in imperative mood
• starts with a present-tense verb, for example Add, Fix, or Deprecate
• provides a link to a Phabricator ticket or code commit and, optionally, the author of the change
• (optional) features a prefix, like "Breaking" - for breaking changes. You can also specify a prefix to indicate a subset of API functionality where the change applies or to provide other information, but be sure to do this consistently.

Examples

Wikitext

= Changelog =

== 1.0.0 - 2025-09-17 ==

First stable version of the Changelog page. No longer supports unreleased changes. For more information, see <link>.

=== Changed ===

* Restructure the Changelog content and structure section <link>

=== Added ===

* Add examples <link>
* Clarify scope <link>

=== Removed ===

* '''Breaking:''' remove support for unreleased changes <link>

=== Fixed ===

* Correct errors in Markdown syntax <link>

Markdown

# Changelog

## 1.0.0 - 2025-09-17

First stable version of the Changelog page. No longer supports unreleased changes. For more information, see <link>.

### Changed

- Restructure the Changelog content section <link>

### Added

- Add examples <link>
- Clarify scope <link>

### Removed

- **Breaking:** remove support for unreleased changes <link>

### Fixed

- Correct errors in Markdown syntax <link>

Template

<changelog>
 <page or file title />
 
 <changelog entry - one for each release or API update>
   <changelog entry heading><API version - if used /> - <date in ISO 8601 format /></changelog entry heading>
   
   <changelog entry notice />
   
   <change group - included 1-4 times>
     <change group heading>Changed|Added|Removed|Fixed</change group heading>
	 
     <list of changes>
       <change><verb /><rest of the change description /><link to ticket or commit /><author - optional /></change>
     </list of changes>
   </change group>
 </changelog entry>
</changelog>

Internationalization

Key considerations for internationalization of an on-wiki changelog:

• Follow internationalization guidelines and processes described on Meta:Internationalization_guidelines, Meta:Internationalization_guidelines/Tutorial, and Help:Extension:Translate/Page_translation_administration.
• Only add translation markup to sections that are unlikely to change in the future.
• Use Template:Draft-section (or a similar notice) to mark sections that are a work in progress. This will help prevent accidental translation of unfinished content.
• Avoid changing content that's already marked for translation.