Release Note Template¶
Applies to: All subscriptions
Purpose¶
Define the structure every Complifly release note follows, so a reader can find what obliges them within seconds of opening it.
Audience¶
Whoever writes release notes. Also useful to readers, who can then predict the layout.
Prerequisites¶
Reference¶
The template¶
# Release 2026.09
**Released:** 2026-09-15
**Upgrade from:** 2026.07 or later
**Estimated window:** 45 minutes
---
## Action required
Everything the customer must do. If empty, say "None" explicitly — an absent
section reads as an oversight, "None" reads as a decision.
| # | Action | Applies to | When |
|---|--------|-----------|------|
| 1 | Run migration 20260915_xyz.sql | All | During the upgrade |
| 2 | Set NEW_SETTING in the environment file | All | Before starting |
| 3 | Update ERP consumers for the changed field | Integrations using X | Before upgrading |
## Breaking changes
What will stop working, and what to do. Include the old and new shapes.
## Deprecations
What still works but will not in future, with the version it is removed in.
## New features
What is now available, and what it requires to use.
## Changes to defaults
Any default that has changed. Behaviour changes on systems nobody touched, so
this deserves its own section rather than a line among the fixes.
## Fixes
What was wrong and is now fixed. Describe the symptom a customer would have
seen, not the internal cause.
## Known issues
What is still wrong, with any workaround.
## Migrations
Every migration in this release, in order, with what each does and roughly how
long it takes at scale.
Rules for writing one¶
| Rule | Reason |
|---|---|
| Action required comes first | It is the only section some readers need |
| Say "None" rather than omitting a section | An absent section is ambiguous |
| Write fixes as the symptom, not the cause | The customer recognises the symptom, not the internal defect |
| State the version a deprecation is removed in | "Deprecated" without a date produces no action |
| Give migration durations at scale | Windows are planned from these |
| Give default changes their own section | They change behaviour on untouched systems |
| Never bury a breaking change among features | It will be missed, and an integration will fail |
Fixes: symptom, not cause¶
| Poor | Good |
|---|---|
| "Fixed null reference in the print service" | "Printing an e-Way Bill generated before the August release no longer fails with an invalid column error" |
| "Corrected rate lookup ordering" | "A bulk rate upload no longer applies effective dates one day early" |
The customer searches for what they experienced. Write the entry so that search finds it.
Validation¶
| Check | Pass condition |
|---|---|
| Action section present | Even if it says "None" |
| Breaking changes prominent | Not buried among features |
| Deprecations dated | With a removal version |
| Migrations listed with durations | Windows can be planned |
| Fixes written as symptoms | Searchable by what the customer saw |
| Default changes called out | In their own section |
| Published before or at availability | Not afterwards |
Troubleshooting¶
| Symptom | Cause | Action |
|---|---|---|
| Customers miss required actions | Buried, or the section is absent | Put actions first; always include the section |
| An integration broke unannounced | A breaking change listed as a feature | Breaking changes get their own section |
| Windows planned too short | No migration durations given | Include them, measured at scale |
| Customers cannot find their fix | Written as an internal cause | Rewrite as the observable symptom |
| A deprecation is ignored | No removal version stated | Always state one |