Release notes and changelogs
The quality of release notes and changelogs can determine how much users trust new features, and how much they trust Unity. To support quality and consistency in your work and within your team, share this document and encourage everybody to follow the same standards.
For information about submitting release notes, refer to the Release Management Confluence space: Release Notes guidelines.
Goals for release notes and changelogs​
Aim to apply the same quality to release notes and changelogs as to the development of Unity. Users often use release notes and changelogs to get a summary of what Unity is releasing, and to get a glimpse into internal development priorities.
A good release note has the following qualities:
- It clearly describes what’s new, what’s changed, or what's been deprecated or removed.
- It is concise enough for a user to skim-read and understand.
- It demonstrates high enough quality to maintain users’ trust in Unity.
- It links to related documentation, where relevant.
Tips for writing good release notes and changelogs​
Use past tense​
Use an action verb in past tense for the first word of your release note. For example, “Added”, “Removed”, “Fixed”, “Moved”, “Implemented”, “Modified”.
| Incorrect | Correct |
|---|---|
| Player tab in Project Settings window now has X button. | Added X button to Player tab in Project Settings window. |
Use plain English and full sentences​
While a certain amount of jargon is expected in technical release notes and changelogs, remember that users are context-switching a lot. Describe your change in one or two easy sentences. Be sure to add the final period at the end.
| Incorrect | Correct |
|---|---|
| Added diagnostic capabilities to crit failure warning in PackMan, user can trigger Unity close and diagnose window. | Added a Diagnose button to the Unity Package Manager’s critical failure warning. You can click the Diagnose button to close Unity and launch the Package Manager Diagnostics tool. |
Describe what a feature does now​
Don't describe what a feature used to do. Instead, document what the update means for the product now.
| Incorrect | Correct |
|---|---|
| Sub Emitter particles were not randomized when using Auto Random Seed. | Modified Sub Emitter particles so that they randomize when using Auto Random Seed. |
| Fixed an issue with the CPU Usage Profiler module's View Type dropdown menu where it would disappear when switching to Hierarchy view without data to display. | Fixed the CPU Usage Profiler module's View Type dropdown menu so it now remains in view when switching to Hierarchy view without data to display. |
Provide straightforward information that is easy to skim-read​
Don’t make release notes and changelogs funny or jokey, and don’t use memes or emojis.
| Incorrect | Correct |
|---|---|
| Analysis, heck yeah! We added Roslyn analyser compatibility, so get stuck in. Awesomesauce! | Added Roslyn analyser compatibility. |
Provide a link to the documentation for the feature​
To keep the link concise and easy to read, just write “Refer to” and the name of the page as a hyperlink.
| Incorrect | Correct |
|---|---|
| Added Roslyn analyser compatibility. Click here for more information. | Added Roslyn analyser compatibility. Refer to Roslyn analyzers and ruleset files. |
Style and formatting for release notes and changelogs​
- Use sentence-style capitalization, grammar, and punctuation for all release notes.
- Use the same text formatting as in regular text. In other words, format UI controls in bold and APIs and code snippets in monospace. For more information on choosing the appropriate formatting, refer to Choose between regular, bold, or monospace font.
- If a release note has several items, provide them in a bulleted list underneath an introductory sentence.
- If a release note has a publicly viewable FogBugz case, then add a link to the case number in parentheses at the end of the text, after the period. The text should still articulate what changed.
For example: "Modified Sub Emitter particles so that they randomize when using Auto Random Seed. (123456)."
Common issues in Unity release notes and changelogs​
Using Jira ticket titles as release notes.​
Don’t just copy and paste a Jira ticket title for your release note or changelog. They don’t always provide enough information for a user to understand at a glance, and they don’t meet our quality standards. Use the guidance in this document to turn the information into a useful release note or changelog.
Using “legacy” to refer to older versions of a feature.​
Use "legacy" only for features that have "legacy" in their name (for example, Legacy Animation system, Legacy shaders). To refer to unsupported features, use one of the following:
- Use "deprecated" to refer to features and functionalities that are unsupported and due to be removed in later versions of Unity, or packages that are no longer supported. Use "marked for deprecation" if a feature is currently supported and safe to use, but a replacement is planned for it in the future.
- Use "obsolete" to refer to APIs that are marked as obsolete.