Changelogs and upgrade notes
This page is for engineers who write the record of a change, and for those who read it before an upgrade. Exponential keeps two records with different jobs: the changelog says what changed, the upgrade notes say what to do about it.
Contents
- Where the records are
- The changelog
- Upgrade notes
- Writing the record of your change
- Reading the record before an upgrade
Where the records are
| Record | Location | Example |
|---|---|---|
| Kernel changelog per version | doc/changelogs/<series>/<version>.md | 6.0.15 |
| Extension changelogs | doc/changelogs/extensions/<name>.md | Exponential Velocity |
| Upgrade notes per change | doc/eng-us/bc/<series>/ | Trusted proxies |
| Checklists per period | doc/eng-us/bc/6.0/behaviour-changes-*.md | Behaviour changes of 1 and 2 October 2026 |
| Feature pages | doc/eng-us/features/6.0/ | Quality checks |
Older series back to 2.9 are kept in doc/changelogs/ for history.
The changelog
- One page per release; entries grouped as Added, Updated, Removed and Renamed (the 6.0.15 page also by period, because the line is long).
- Each page starts with Upgrading, which links the upgrade notes in the order to read them.
- Entries are assembled from commit subjects, which use the same prefixes (
Added:,Updated:,Fixed:,Removed:,Renamed:); fixes appear under Updated in the Velocity changelog. - A page for a version in development says so on its first line ("Not released yet").
Upgrade notes
Every change that needs action from an installation, or behaves differently without being asked to, gets a page in
doc/eng-us/bc/<series>/. A page opens with an In short table:
| Row | Answers |
|---|---|
| What changed | the behavior before and after |
| Who is affected | which installations, extensions or users |
| How to check | a command or a page that shows whether you are affected |
| How to fix | what to do, or how to undo it deliberately |
Changes that span many areas are collected per period with a deploy order and a checklist table. See Backward compatibility policy for what counts as such a change.
Writing the record of your change
- Write the commit subject with the right prefix; the body says why and what (Git workflow).
- Add the entry to the changelog page of the version in development, under the matching section.
- If an installation must act, write the upgrade note with the four rows, and link it from the changelog's Upgrading section.
- A new setting gets its feature page section and a line in the changelog.
- Name the product Exponential, and keep identifiers such as
eZINIas they are. - Check the pages with
exp:help check(Documentation as code).
Reading the record before an upgrade
Read the Upgrading section of every version you pass, then the checklist of every period in the order it gives, then the changelogs of the extensions you use. The upgrade guide walks through it (Upgrading).
Related pages
- Changelogs, for extension maintainers
- Commit messages
- Release engineering
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.