One changelog entry should describe one confirmed change: release identifier, effective date, affected users, behaviour before and after, and any required action. This template concerns an already deployed feature rather than an announcement of a first launch.
Collect facts for one change
Get confirmation from the feature owner before writing. You need the user-facing name, release identifier, actual deployment time and affected users. Do not turn a planned schedule into an effective date. If only some accounts have access, identify that group.
Separate the feature name from the internal ticket number. A ticket helps the team recover a decision, but rarely explains the product to customers. The entry should make sense without internal notes.
Record the version and date accurately
Use the release identifier adopted by the product. Do not invent a number for the article. If the product uses SemVer, interpret its components according to its rules and declared public API. Other numbering systems may not express the same change scale.
Write an unambiguous date, such as YYYY-MM-DD. Include a time zone if the time matters. The entry's writing date can differ. For staged deployment, state the starting point and current coverage instead of suggesting simultaneous access for everyone.
Describe before and after
Use two short statements: “Before the change…” and “After the change…”. Identify behaviour users actually experience. Explain who is affected and any required action. If no action is necessary, say so.
Do not claim unverified benefits. A filtering change does not establish increased sales or a particular number of hours saved. Explain the new capability and its limits. Pricing and billing rules belong in their appropriate documentation.
Example of one entry
This fictional example does not describe a Semly release.
- Feature: filtering a document list.
- Release: 2.4.1, using the example product's numbering.
- Effective date: 2026-10-12.
- Before: selecting a second filter removed the first.
- After: the list applies both selected filters together.
- Coverage: version 2.4.1 users working with the document list.
- User action: refresh the open list after updating.
- Limit: saved filter templates are unaffected.
The limit prevents readers from guessing whether templates changed too. In a real entry, add a verified link to that feature's documentation. If documentation does not exist, describe the required step rather than inventing a URL.
Check the entry before saving
Compare every field with product-team confirmation. Check version, date, coverage and behaviour. Confirm that the action can be performed and that any link reaches current instructions.
Read without ticket context. Can someone identify what changed and when? If several independent features appear, split them into separate entries within the release. Do not create several articles about the same change.
Preserve meaning across languages
Translations retain release identifier, deployment time, coverage and limits. Localising a message does not confirm feature availability in a new market. State country differences explicitly.
When correcting an entry, keep the true deployment date and label the description update. An editorial correction is not another deployment. This produces a concise, verifiable record of one change.
Source for version numbering
SemVer rules concern a declared public API. They are not a mandatory numbering scheme for every SaaS product.
