Guide to upgrade.txt
What is upgrade.txt?
The upgrade.txt file is designed to describe any technical changes to components.
Any changes in a module should have its own upgrade.txt file containing changes in core libraries and APIs. If this file doesn't exist for the module you have made the changes in then it should be added.
What is the goal?
Developers may modify the codebase and use our core libraries and public APIs (public methods in classes, functions, etc) in their own plugins or implementations. The upgrade.txt file is designed to inform external developers of upcoming changes which may affect their modifications or systems.
What is a public API?
A public API isn’t just something you access via a REST client. Public APIs also include any publicly accessible or protected methods and properties within classes, TUI components, and core libraries. When deciding whether something constitutes a public API, consider the perspective of a developer building on top of Totara. If your change affects existing integrations, implementations, or systems that rely on the area you're modifying, it's likely part of the public API. Such changes must be documented in the upgrade.txt file.
Formatting
Sample Header
This is a sample header for the file
This files describes API changes in core libraries and APIs,
information provided here is intended especially for developers.
=== 11.4 ===
* hello::world() is now deprecated...Version headers
All changes to a particular version should be grouped by a version header. Version headers should be prefixed and suffixed with three equals signs (=).
The version header should have a new line directly underneath it. The first entry should go below this new line.
Examples:
=== 20.0.0 ===
* My first entry for this version=== 11.1 ===
* My first entry for this version
* My second entry for this versionLayout
Entries should be bullet points using an asterisk and a space:
* Removed deprecated completion_info::wipe_session_cache()
For multiple level of bullet points add 2 spaces in front of the asterisk for each level:
* Removed deprecated methods from classes:
* \totara_reportbuilder\rb\display\base:
* my_deprecated_function_1
* my_deprecated_function_2
* New mustache template for add block popoverWhen to create an entry
Output changes
Whenever a renderer or a mustache template changes, there should be an entry in the upgrade.txt. This is so that themes built upon these templates receive notice that their theme may need to be updated.
In the case where there is already a mention for the release, it does not need to be duplicated.
Internal changes to an existing public API (no change to output)
When an internal change is made to public API but the output of the API doesn’t change, we should still add an entry to the version.txt, as there may be modifications from the external developer to the method.
Example
If we had the following existing code:
public function add_twice($a, $b): int {
$sum = $a + $b;
return $sum * 2;
} and updated it to:
public function add($a, $b) {
return $a + $b;
}
public function add_twice($a, $b): int {
$sum = $this->add($a, $b);
return $sum * 2;
} This new code does not change the output of the method add_twice(), so usages of the method should not break. However, internal modifications from an external developer to the method could causes issues when updating to this new patch.
For this change, we would add two upgrade.txt entries.
one for the new
add()method and,one for the internal modification to our
add_twice()public API method.
The upgrade.txt entry may look something like:
=== 20.0.0 ===
* Added a new method `\namespace\of\class::add()` - This method takes two parameters and adds them together.
* Modified internal implementation of method `\namespace\of\class::add_twice()` to utilise the new `::add()` method.
More examples
See the Deprecation guidelines for more examples of where upgrade.txt entries would be necessary.
FAQ
What if my change goes to multiple versions?
If your change applies to multiple versions, the upgrade.txt should specify when the change was first introduced in each version. For example, if ticket TL-123 applies to three versions: main-19, stable-19, and main, the upgrade.txt will look like this:
Branch name: TL-123/main-19
=== 19.1.0 ===
* My new technical changeBranch name: TL-123/stable-19
=== 19.0.1 ===
* My new technical changeBranch name: TL-123/main
=== 20.0.0 ===
* My new technical change