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.
It also plays a key role when compiling the technical release notes for each major release.
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 PHP 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 is likely to affect existing integrations, customisations, plugin 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.
=== 19.1.0 ===
* 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 versionWhen cherry-picking patches to other branches, pay particular attention to ensure that upgrade.txt entries are correctly versioned for the next release on that branch.
Layout
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
The upgrade.txt entries are focused on change to APIs that have already been released. We generally don’t need to add entries for new things unless we think it is important for plugin developers to know about them, or because they give the reader context for other changes.
Changes which must be noted
Breaking changes
Deprecations
Changes to public method/function signatures
New hooks and events
Cases where functionality has been moved to other components or namespaces
Important upgrades
Refactoring of legacy UX to Tui
Security, accessibility, or performance fixes that need to be propagated to customisations
Fixes for compatibility with upgraded dependencies (eg fixes for new versions of PHP)
New external API queries/mutations, and capabilities added to ‘API User’ archetype
For all of these, put yourself in the shoes of a developer with plugins that may need to be updated; what do you need to know to discover and fix the issues?
Other changes to note
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 PHP 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.Changes to testing generator
When a change is made to the testing generator, we should add an entry to the upgrade.txt. For example, if we added a new method or changed how an existing method works, we want to notify external developers so they can implement these changes in their own tests.
Deprecation 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