Release note and changelog quality 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.
Goals for good release notes and changelogs
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. We should always aim to apply the same quality to our release notes and changelogs as we do for the development of Unity.
A good release note should:
Clearly describe what’s new, or what’s changed
Be concise enough for a user to skim-read and understand
Demonstrate high enough quality to maintain users’ trust in Unity
Link to related documentation, where relevant
Tips for writing good release notes and changelogs
Use past tense. The first word of your release note should ideally be an action in past tense; for example, “Added”, “Removed”, “Fixed”, “Moved”, “Implemented”, “Modified”.
Player Settings now has X button.
Added X button to Player Settings.
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, and they should be able to understand your change in one or two easy sentences.
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, rather than what a feature used to do.
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 where it would disappear when switching to Hierarchy View without data to display.
Fixed the CPU Usage Profiler module's View Type dropdown 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.
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 this concise and easy to read, just write “See” and the name of the page as a hyperlink.
Added Roslyn analyser compatibility. Click here for more information.
Use sentence-style capitalization and grammar for all release notes.
Format Editor properties, menu items and settings in bold text.
Format APIs and code snippets in monospace text.
If a release note has several items, provide them in a bullet list underneath an introductory sentence.
Common issues in Unity release notes and changelogs
Using FogBugz case titles as release notes. Don’t just copy and paste a FogBugz cases 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.
Linking to Fogbugz case notes. You can optionally include the case number and a link, but only if the case is publicly viewable. The changelog should still articulate what changed. For example:
"Modified Sub Emitter particles so that they randomize when using Auto Random Seed (case 123456)."
Using “legacy” to refer to older versions of a feature. Only use “legacy” for features that have “legacy” in their name (for example, Legacy Animation system, Legacy shaders). Instead, use one of the following to refer to unsupported features:
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.