chore(docs): add release note guidelines

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,7 @@
 <!-- If this is a breaking change, explain why it is necessary. Breaking changes must append `!` after the type/scope. See https://ddtrace.readthedocs.io/en/stable/contributing.html for more details. -->
 
 ## Checklist
+- [ ] Followed the [library release note guidelines](https://ddtrace.readthedocs.io/en/stable/contributing.html#Release-Note-Guidelines) when writing a release note.
 - [ ] Add additional sections for `feat` and `fix` pull requests.
 - [ ] [Library documentation](https://github.com/DataDog/dd-trace-py/tree/1.x/docs) and/or [Datadog's documentation site](https://github.com/DataDog/documentation/) is updated. Link to doc PR in description.
 
@@ -38,6 +39,6 @@
 - [ ] No unnecessary changes were introduced in this PR.
 - [ ] Avoid breaking [API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces) changes unless absolutely necessary.
 - [ ] Tests provided or description of manual testing performed is included in the code or PR.
-- [ ] Release note has been added for fixes and features, or else `changelog/no-changelog` label added.
+- [ ] Release note has been added and follows the [library release note guidelines](https://ddtrace.readthedocs.io/en/stable/contributing.html#Release-Note-Guidelines), or else `changelog/no-changelog` label added.
 - [ ] All relevant GitHub issues are correctly linked.
 - [ ] Backports are identified and tagged with Mergifyio.

README.md

@@ -154,10 +154,7 @@ After installing the `circleci` CLI, you can run jobs by name. For example:
 ### Release Notes
 
 This project follows [semver](https://semver.org/) and so bug fixes, breaking
-changes, new features, etc must be accompanied by a release note. To generate a
-release note:
+changes, new features, etc must be accompanied by a release note. 
 
-    $ riot run reno new <short-description-of-change>
-
-Document the changes in the generated file, remove the irrelevant sections and
-commit the release note with the change.
+See the [contributing docs](https://ddtrace.readthedocs.io/en/stable/contributing.html) for
+instructions on generating, writing, formatting, and styling release notes.

docs/contributing.rst

@@ -46,6 +46,159 @@ a human. All code style enforcement must be automated to avoid bikeshedding
 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.
+
+Requiring a Release Note
+++++++++++++++++++++++++
+
+A release note is **required** if a PR is user-impacting, or if it meets any of the following conditions:
+
+* `Breaking change to the public API <https://ddtrace.readthedocs.io/en/stable/versioning.html#release-versions>`_
+* New feature
+* Bug fix
+* Deprecations
+* Dependency upgrades
+
+Otherwise, a release note is not required.
+Examples of when a release note is **not required** are:
+
+* CI chores (e.g., upgrade/pinning dependency versions to fix CI)
+* Changes to internal API (Non-public facing, or not-yet released components/features)
+
+Release Note Style Guidelines
++++++++++++++++++++++++++++++
+
+The main goal of a release note is to provide a brief overview of a change.
+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.
+* 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.
+
+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.
+
+Generally, the format of the ``<title-slug>`` is lowercase words separated by hyphens.
+
+For example:
+
+* ``fix-aioredis-catch-canceled-error``
+* ``deprecate-tracer-writer``
+
+Release Note Sections
++++++++++++++++++++++
+
+Generated release note files are templates and include all possible categories.
+All irrelevant sections should be removed for the final release note.
+Once finished, the release note should be committed with the rest of the changes.
+
+* Features: New features such as a new integration or component. For example::
+
+    features:
+    - |
+      graphene: Adds support for ``graphene>=2``. `See the graphql documentation <https://ddtrace.readthedocs.io/en/1.6.0/integrations.html#graphql>`_
+      for more information.
+
+* Upgrade: Enhanced functionality or if dependencies are upgraded. Also used for if components are removed. Usually includes instruction or recommendation to user in regards to how to adjust to the new change. For example::
+
+    upgrade:
+    - |
+      tracing: Use ``Span.set_tag_str()`` instead of ``Span.set_tag()`` when the tag value is a
+      text type as a performance optimization in manual instrumentation.
+
+* Deprecations: Warning of a component being removed from the public API in the future. For example::
+
+    deprecations:
+    - |
+      tracing: ``ddtrace.Span.meta`` has been deprecated. Use ``ddtrace.Span.get_tag`` and ``ddtrace.Span.set_tag`` instead.
+
+* Fixes: Bug fixes. For example::
+
+    fixes:
+    - |
+      django: Fixes an issue where a manually set ``django.request`` span resource would get overwritten by the integration.
+
+* Other: Any change which does not fall into any of the above categories. For example::
+
+    other:
+    - |
+      docs: Adds documentation on how to use Gunicorn with the ``gevent`` worker class.
+
+* Prelude: Not required for every change. Required for major changes such as a new component or new feature which would benefit the user by providing additional context or theme. For example::
+
+    prelude: >
+      dynamic instrumentation: Dynamic Instrumentation allows instrumenting a running service dynamically
+      to extract runtime information that could be useful for, e.g., debugging
+      purposes, or to add extra metrics without having to make code changes and
+      re-deploy the service. See https://ddtrace.readthedocs.io/en/1.6.0/configuration.html
+      for more details.
+    features:
+    - |
+      dynamic instrumentation: Introduces the public interface for the dynamic instrumentation service. See
+      https://ddtrace.readthedocs.io/en/1.6.0/configuration.html for more details.
+
+Release Note Formatting
++++++++++++++++++++++++
+
+In general, a release note entry should follow the following format::
+
+  ---
+  <section>:
+    - |
+      scope: note
+
+Scope
+~~~~~
+
+This is a one-word scope, which is ideally the name of the library component, sub-component or integration
+that is impacted by this change. This should not be capitalized unless it is an acronym.
+
+To ensure consistency in component naming, the convention in referring to components is as follows:
+
+* Tracer: ``tracing``
+* Profiler: ``profiling``
+* Application Security Monitoring: ``ASM``
+* Dynamic Instrumentation: ``dynamic instrumentation``
+* CI Visibility: ``CI visibility``
+* Integrations: ``integration_name``
+
+Note
+~~~~
+
+The note is a brief description of the change. It should consist of full sentence(s) with sentence-case capitalization.
+The note should also follow valid restructured text (RST) formatting. See the template release note for
+more details and instructions.
+
 How To: Write an Integration
 ============================
 

releasenotes/template-release-note.yaml

@@ -0,0 +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.
+    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:
+    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:
+    Format: <scope>: This upgrades <present_tense_explanation>. With this upgrade, you can <actionable_step_for_user>.
+  - |
+    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:
+    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:
+    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.
+    Format: <scope>: <add_release_note_here>.