Project Delivery
Write release notes for users rather than commit lists
Commit history explains implementation, not what a user should do next. Organize release notes around changed tasks, affected audiences, required actions, and known limitations so customers can assess whether a release matters to them.
A release note should help a user decide whether to adopt a change, adjust a workflow, or ask for support. A list of internal ticket titles rarely answers those questions. Start with the change people can observe and the action they may need. Preserve technical references for traceability, but do not make customers translate implementation language into business consequences.
Separate the release package from the explanation
GitHub describes releases as a way to package software with release notes and links to binary files.[4] That mechanism provides a place for the explanation. It does not decide which details are relevant to customers. Treat the generated commit list as editorial input, not the finished message.
Group changes by audience or task when that makes navigation easier. Distinguish new behavior, corrected behavior, required migration, and known limitations. Avoid calling every small correction an improvement without explaining what a person will now experience differently. Leave internal refactoring out unless it creates a material user consequence.
Write an entry that supports action
For each important change, state the affected role, the previous behavior when necessary, the new behavior, and any action required. Explain whether the change applies to everyone or only to an enabled group. Do not describe availability more broadly than the actual release scope.
Use these checks before approving the customer version.
- Name the user task instead of copying an internal ticket title.
- State whether users need to change settings or repeat work.
- Identify role, plan, or rollout restrictions when relevant.
- Link instructions for changes that require several steps.
- Include known limitations and the appropriate support route.
Hypothetical example: saved export filters
In a hypothetical reporting tool, the implementation history mentions query persistence and a configuration update. The user note instead explains that analysts can save export filters for reuse, where the save control appears, and whether existing exports retain their current behavior.
If saved filters are initially available only to a pilot group, the note says so. If filters do not include column ordering, that limitation appears beside the feature description. The customer can now decide whether the feature supports their task without interpreting code terminology or assuming a broader capability.
Review accuracy before polishing tone
Ask product, delivery, and support representatives to verify the note against the actual release. Check behavior on the identified build, particularly instructions that modify data or remove old options. Keep private customer details, sensitive technical configuration, and speculative future promises out of the public text.
Too much detail can hide an important required action. Too little can leave users unprepared. Put consequential actions first and offer deeper instructions through links. For the next release, rewrite one technical entry as a task-based explanation, then ask someone outside the implementation team what they would do differently after reading it.
