Release notes and changelogs
If the Unity Style Guide doesn't have what you're looking for, check the Microsoft Style Guide.
This document provides the following at-a-glance guidance for writing release notes and changelogs at Unity:
    Goals for good release notes and changelogs
    Tips for writing good release notes and changelogs
    Formatting release notes and changelogs
    Common issues in Unity release notes and changelogs
For information on submitting release notes, see the Release Management Confluence space: Release Notes guidelines.
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”.
    Incorrect
    Correct
    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.
    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, rather than what a feature used to do.
    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 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.
    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 this concise and easy to read, just write “See” and the name of the page as a hyperlink.
    Incorrect
    Correct
    Added Roslyn analyser compatibility. Click here for more information.
    Added Roslyn analyser compatibility. See Roslyn analyzers and ruleset files.

Formatting release notes and changelogs

    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.
Last modified 5mo ago