Definition
Changelog (Change Log) records the update contents, fixes, and known issues of OTA firmware versions, facilitating operations and customer understanding of version differences, and assisting upgrade decisions. It is often integrated with CI/CD pipelines for automatic generation.
Content Specification
Changelogs are usually organized by version number, with each entry containing categories such as Added features (Added), Fixed issues (Fixed), Known issues (Known Issues), and Breaking changes (Breaking Changes). When using semantic versioning (SemVer), this can correspond to Major.Minor.Patch change levels. The format can follow specifications such as Keep a Changelog to facilitate both machine parsing and human reading.
Automated Generation
In the CI/CD pipeline, Changelog entries can be automatically generated from Git commit messages, issue associations, and PR descriptions. Tools such as conventional-changelog can parse commits based on the Conventional Commits specification, reducing manual maintenance costs and ensuring that every OTA release has traceable change documentation.
Integration with the OTA release process
When creating an OTA task in the Device Management Platform, you can associate Changelog content, which is displayed to operations personnel or customers on the upgrade confirmation page. For scenarios like grayscale upgrades or phased push, a clear Changelog helps assess upgrade risks and decide whether to expand the push scope or perform a Rollback.
What one version note must state at minimum
A changelog means a difference note, for every firmware version that can be delivered, that both a person and a machine can match. It is not a paste of the repository commit log. It has to answer which older version it is relative to, what behavior changed, what defect was fixed, what is still unfixed, and which changes make an old configuration or an old protocol no longer applicable. The version number, the release time, and the applicable product belong in the same entry. “Improved stability” alone cannot decide whether a device stuck on an old version should move. The note should freeze with the version. A published entry is not rewritten to match a spoken explanation. If it is found to be wrong, a correction is appended. The history is not quietly replaced.
A changelog should be required when a version will reach the field by over-the-air upgrade and several old versions are still in the field. A temporary package that never leaves a test group can use a short record, but once it enters a release list that can be selected, the note should be completed. The note must correspond to the source version declared by the delta package. The difference from version A to version C cannot be filled with the note for version B. Breaking changes should be listed on their own, such as a renamed property, a changed default threshold, or a changed boot-partition layout, because those decide whether an overwrite install is safe.
When a note that is too coarse causes a wrong upgrade
A common mistake is to collapse several days of commit titles into “fixed several issues,” so operations cannot tell whether this release contains the one defect they have been waiting for. Another is to list only new features, not known issues and rollback limits. When something goes wrong during a canary, the note still looks like an ordinary release. Skipping version numbers without saying whether the versions in between are required also puts the delta upgrade path and the note out of alignment. Generating the note from commit messages does not replace a review if developers use vague commit titles. The generated result is equally vague.
Do not write a change that has not been merged into a version already published, and do not describe an experimental feature as on by default. If device behavior depends on compile switches, the note should say which switches this version actually turned on. Relative to firmware signature, the signature guarantees the package was not swapped, and the changelog guarantees that a person understands what is in the package. Neither replaces the other. A “there was also a protocol change” added only after publication is a documentation incident. Devices already upgraded need to be reassessed. Changing the words on the page is not enough.
When a published note is found to be wrong
After a version can be downloaded by devices, the change note is bound to that package. If a protocol change was left out, or a defect number was written wrong, append a correction under the original entry, with the correction time and which sentence was corrected. Do not replace the original so that it looks as if it was never wrong. Replacement leaves the person who approved the upgrade from the old note unable to explain why they released it. If the error is serious enough to affect the safety or compatibility of devices already upgraded, publish a separate note naming which versions are affected and whether to stay on a version or continue to another. Do not only change the page title. A note that is still a candidate and not yet published may be edited, but the text finally published and the final package must be the same candidate.
A draft generated automatically from commit titles must be read, before publication, by someone who understands the behavior change. Internal code names, cancelled experiments, and fixes that were not merged should not appear in the text used for an upgrade decision. The reverse is also true. A change a user can perceive, such as a default threshold, a partition layout, or a configuration field name, must be added to the note even if the commit title omitted it. A note that cannot answer whether the old configuration can still be used after moving up from the current version is not yet fit to ship with the package. Before writing “none” under known issues, confirm that this version really has no open defect that affects the upgrade, rather than leaving the field empty because nobody filled it in. If a correction concerns a version already running in the field, it should also name the affected version range and the recommended next step, not only add an easy-to-miss remark at the bottom of the page.