Wikimedia APIs/Changelog/Style guide

This page serves as the style guide for Wikimedia APIs/Changelog. It explains how to write and structure content for the changelog to make it useful, clear, and consistent.

The Wikimedia APIs changelog covers changes to APIs listed in the Wikimedia API catalog. Its purpose is to notify users about changes that might impact their usage of these APIs. For information on how to write a changelog for an individual API not in scope for Wikimedia APIs/Changelog, see Documentation/API_documentation/Changelog.

Content overview

What to include

The Wikimedia APIs/Changelog page contains:

information about noteworthy changes
information about breaking changes and how to deal with them
links to extra information, typically Phabricator tasks, code commits, and documentation

What not to include

The Wikimedia APIs/Changelog page doesn't contain:

unedited copy of git log or commit history
changes within a single release that cancel each other (for example reverted commits)
extended documentation on how to deal with changes - this documentation should be available elsewhere

When to make changes

As a maintainer of an API, consider updating Wikimedia APIs/Changelog when you:

release new features
make changes that impact parameters accepted or responses returned by the API
fix bugs
deprecate existing functionality
remove features

Full content and structure

The Wikimedia APIs/Changelog page contains changes grouped by month and change type, for example:

== January 2026 ==
 
=== Removed ===
 
* '''MediaWiki REST API''' - {{Breaking}} Sunset and remove support for Transform endpoints reflecting the trailing slash implementation pattern. You can use non-trailing slash versions instead. (Week of January 26, [[phab:T404855|T404855]])

Month

The first level of page structure is month. When adding a new month to the changelog:

Write the heading as <full month name> <four-digit year>, for example, "February 2026".
Add the new section at the top and make sure sections are in reverse-chronological order. There's typically no need to add sections for future months.
For changes released over a longer time, place the entry in the month corresponding to the beginning of the release period. For example, describe changes released between 2026-03-30 and 2026-04-03 in March 2026.
Add one or more sections representing different change types as described in #Change_type.

Change type

The second level of page structure under each month is change type. Use the following headings (always in the specified order) on this level:

Changed - general changes in API behavior, accepted parameters, and returned responses. Deprecations also belong under this heading.
Added - new features
Removed - removals of functionality, after deprecating the same functionality in a change announced earlier
Fixed - changes that address specific unintended behavior

Each section representing a change type contains a list with one or more changes (main changelog entries).

Change

Add changes under appropriate month and change type headings. Each change, represented by a list item, follows the same format:

<API name> - <Breaking|Deprecation> <change description> (<month day>, <Phabricator task>, <commit>, <docs>)

API name - prefix indicating the API the change applies to, formatted as bold text. For example, "MediaWiki REST API", or "Action API"
Breaking or Deprecation - an optional "Breaking" or "Deprecation" label to indicate a breaking change or deprecation. Use Template:Breaking or Template:Deprecation to display the label.
Change description - self-contained description of a change. Write it in imperative mood, starting with a present-tense verb, like "Add", "Fix", "Deprecate", or "Remove".
Extra information in parentheses, in the following order:
- date written as <full month name> <day number>, for example "October 20". If the precise date is impossible to provide, use week of <full month name> <day number> or <full month name> instead.
- link to the relevant Phabricator task
- link to the relevant commit in a version control system or forge (typically Wikimedia Gerrit or GitLab)
- link to the relevant documentation