Add guidelines to template release note

docs/contributing.rst

@@ -47,7 +47,7 @@ and losing time.
 
 
 Release Notes
-=======================
+=============
 Release notes are the primary product documentation a user will see when updating the library. Therefore, we must take care to ensure the quality of release notes.
 
 A release note entry should be included for every pull request that changes how a user interacts with the library.
@@ -78,37 +78,42 @@ If necessary, we can also provide actionable steps to the user.
 The release note should clearly communicate what the change is, why the change was made,
 and how a user can migrate their code.
 
+The release note should also clearly distinguish between announcements and user instructions. Use:
+
+* Past tense for previous/existing behavior (ex: ``resulted, caused, failed``)
+* Third person present tense for the change itself (ex: ``adds, fixes, upgrades``)
+* Active present infinitive for user instructions (ex: ``set, use, add``)
+
 Release notes should:
 
-* Use plain language
-* Avoid overly technical language
-* Be concise
-* Include actionable steps with the necessary code changes
-* Include relevant links (bug issues, upstream issues or release notes, documentation pages)
-* Be full sentences with proper punctuation.
-* Before using specifically acronyms and terminology specific to Datadog, a release note must first introduce them with a definition or explanation.
+* Use plain language.
+* Be concise.
+* Include actionable steps with the necessary code changes.
+* Include relevant links (bug issues, upstream issues or release notes, documentation pages).
+* Use full sentences with sentence-casing and punctuation.
+* Before using Datadog specific acronyms/terminology, a release note must first introduce them with a definition.
 
 Release notes should not:
 
 * Be vague. Example: ``fixes an issue in tracing``.
-* Use acronyms liberally. If an acronym must be used, the acronym should be introduced in the first occurrence of the full term in parentheses immediately after the full term.
-* Use dynamic links (``stable/latest/1.x`` URLs). Instead, use static links (specific version, commit hash/tag) whenever possible so that they don't break in the future.
+* Use overly technical language.
+* Use dynamic links (``stable/latest/1.x`` URLs). Instead, use static links (specific version, commit hash) whenever possible so that they don't break in the future.
 
 Generating a Release Note
 +++++++++++++++++++++++++
 Release notes are generated with the command line tool ``reno`` which can be used with riot::
 
     $ riot run reno new <title-slug>
 
-The <title-slug> is used as the prefix for a new file created in ``releasenotes/notes``.
-The <title-slug> is used internally and is not visible in the the product documentation.
+The ``<title-slug>`` is used as the prefix for a new file created in ``releasenotes/notes``.
+The ``<title-slug>`` is used internally and is not visible in the the product documentation.
 
 Generally, the format of the ``<title-slug>`` is lowercase words separated by hyphens.
 
 For example:
 
-* fix-aioredis-catch-canceled-error
-* deprecate-tracer-writer
+* ``fix-aioredis-catch-canceled-error``
+* ``deprecate-tracer-writer``
 
 Release Note Sections
 +++++++++++++++++++++

releasenotes/template-release-note.yaml

@@ -1,35 +1,60 @@
 ---
+#instructions: >
+#    The style guide below provides explanations, instructions, and templates to write your own release note.
+#    Once finished, all irrelevant sections (including this instruction section) should be removed,
+#    and the release note should be committed with the rest of the changes.
+#
+#    The main goal of a release note is to provide a brief overview of a change and provide actionable steps to the user.
+#    The release note should clearly communicate what the change is, why the change was made, and how a user can migrate their code.
+#
+#    The release note should also clearly distinguish between announcements and user instructions. Use:
+#    * Past tense for previous/existing behavior (ex: ``resulted, caused, failed``)
+#    * Third person present tense for the change itself (ex: ``adds, fixes, upgrades``)
+#    * Active present infinitive for user instructions (ex: ``set, use, add``)
+#
+#    Release notes should:
+#    * Use plain language
+#    * Be concise
+#    * Include actionable steps with the necessary code changes
+#    * Include relevant links (bug issues, upstream issues or release notes, documentation pages)
+#    * Use full sentences with sentence-casing and punctuation.
+#    * Before using Datadog specific acronyms/terminology, a release note must first introduce them with a definition.
+#
+#    Release notes should not:
+#    * Be vague. Example: ``fixes an issue in tracing``.
+#    * Use overly technical language
+#    * Use dynamic links (``stable/latest/1.x`` URLs). Instead, use static links (specific version, commit hash) whenever possible so that they don't break in the future.
 prelude: >
     Usually in tandem with a new feature or major change, meant to provide context or background for a major change. 
     No specific format other than a required scope is provided and the author is requested to use their best judgment.
-    <scope>: <add_prelude_and_context_here>.
+    Format: <scope>: <add_prelude_and_context_here>.
 features:
   - |
     For new features such as a new integration or component. Use present tense with the following format:
-    <scope>: This introduces <new_feature_or_component>. Use present tense here.
+    Format: <scope>: This introduces <new_feature_or_component>.
 upgrade:
   - |
     For enhanced functionality or if package dependencies are upgraded. If applicable, include instructions
     for how a user can migrate their code.
     Use present tense with the following formats, respectively for enhancements or removals:
-    <scope>: This upgrades <present_tense_explanation>. With this upgrade, you can <actionable_step_for_user>.
+    Format: <scope>: This upgrades <present_tense_explanation>. With this upgrade, you can <actionable_step_for_user>.
   - |
-    <scope>: <affected_code> has been removed. As an alternative to <affected_code>, you can use <alternative> instead.
+    Format: <scope>: <affected_code> is now removed. As an alternative to <affected_code>, you can use <alternative> instead.
 deprecations:
   - |
     Warning of a component or member of the public API being removed in the future.
     Use present tense for when deprecation actually happens and future tense for when removal is planned to happen. 
     Include deprecation/removal timeline, as well as workarounds and alternatives in the following format:
-    <scope>: <affected_code> is deprecated and will be removed in <version_to_be_removed>.
-    As an alternative to <affected_code>, you can use <alternative> instead.
+    Format: <scope>: <affected_code> is deprecated and will be removed in <version_to_be_removed>.
+            As an alternative to <affected_code>, you can use <alternative> instead.
 fixes:
   - |
     For reporting bug fixes.
     Use past tense for the problem and present tense for the fix and solution in the following format:
-    <scope>: This fix resolves an issue where <ABC_bug> caused <XYZ_situation>.
+    Format: <scope>: This fix resolves an issue where <ABC_bug> caused <XYZ_situation>.
 other:
   - |
     For any change which does not fall into any of the above categories. Since changes falling into this category are 
     likely rare and not very similar to each other, no specific format other than a required scope is provided. 
     The author is requested to use their best judgment to ensure a quality release note.
-    <scope>: <add_release_note_here>.
+    Format: <scope>: <add_release_note_here>.