Adding changelog to your manifest file

From Joomla! Documentation

Other languages:
English • ‎français • ‎italiano • ‎Nederlands
Joomla! 
4.x
>Tutorial

Since Joomla 4.0, extension developers can leverage the ability of Joomla to read a changelog file and give a visual representation of the changelog. If a given version is not found in the changelog, the changelog button will not be shown.

The changes in a release will be presented in this manner:

Changelog modal

The changelog is used in two different places.

Update View

The installer will show the changelog of the version that can be installed if available.

Changelog button on the Update View

Clicking the Changelog button here will show the changelog of the new available version.

Manage View

The extension manager will show the changelog of the currently installed extension if available.

Version number is a link to the changelog modal

Clicking the version number here will show the changelog of the current installed version.

Update manifest file

The first step is to update your manifest file that tells Joomla where to find the changelog details. Add the following node to your manifest XML file:

<changelogurl>https://example.com/updates/changelog.xml</changelogurl>

Create changelog file

The changelog file must have the following 3 nodes:

  • element
  • type
  • version

This information is used to identify the correct changelog for a given extension.

<element>com_lists</element>
<type>component</type>
<version>4.0.0</version>

Further the changelog is filled with one or more change types. The following change types are supported:

  • security: Any security issues that have been fixed
  • fix: Any bugs that have been fixed
  • language: This is for language changes
  • addition: Any new features added
  • change: Any changes
  • remove: Any features removed
  • note: Any extra information to inform the user

Each node can be repeated as many times as needed.

The format of the text can be plain text or HTML but in case of HTML, it must be enclosed in CDATA tags as shown in the example.

<changelogs>
    <changelog>
        <element>com_lists</element>
        <type>component</type>
        <version>4.0.0</version>
        <security>
            <item>Item A</item>
            <item><![CDATA[<h2>You MUST replace this file</h2>]]></item>
        </security>
        <fix>
            <item>Item A</item>
            <item>Item b</item>
        </fix>
        <language>
            <item>Item A</item>
            <item>Item b</item>
        </language>
        <addition>
            <item>Item A</item>
            <item>Item b</item>
        </addition>
        <change>
            <item>Item A</item>
            <item>Item b</item>
        </change>
        <remove>
            <item>Item A</item>
            <item>Item b</item>
        </remove>
        <note>
            <item>Item A</item>
            <item>Item b</item>
        </note>
</changelog>
<changelog>
	<element>com_lists</element>
	<type>component</type>
	<version>0.0.2</version>
	<security>
		<item>Big issue</item>
	</security>
</changelog>
</changelogs>

This file contains 2 changelogs:

  • Version 0.0.2 (for testing the manage view)
  • Version 4.0.0 (for testing the update view)

A changelog can have as many versions as needed.