Move release note guidelines docs to contributing docs

.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

@@ -156,5 +156,5 @@ After installing the `circleci` CLI, you can run jobs by name. For example:
 This project follows [semver](https://semver.org/) and so bug fixes, breaking
 changes, new features, etc must be accompanied by a release note. 
 
-See the [release note guidelines](https://ddtrace.readthedocs.io/en/stable/release_note_guidelines.html) for
+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,176 @@ a human. All code style enforcement must be automated to avoid bikeshedding
 and losing time.
 
 
+Release Note Guidelines
+=======================
+The guidelines below describe how to ensure consistency and clarity in 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.
+
+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)
+* Before using specifically acronyms and terminology specific to Datadog, a release note must first introduce them with a definition or explanation.
+
+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.
+
+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 follow sentence-case capitalization.
+The note should also follow valid restructured text (RST) formatting.
+
+* Features: Use present tense with the following format::
+
+  <scope>: This introduces <new_feature_or_component>.
+
+* Upgrade: Use present tense with the following formats (upgrade or removal respectively)::
+
+  <scope>: This upgrades <present tense explanation>. With this upgrade, <actionable_step_for_user>.
+  <scope>: <affected_code> has been removed. As an alternative to <affected_code>, you can use <alternative> instead.
+
+* Deprecations: 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.
+
+* 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>.
+
+* Other: 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.
+
+* Prelude: Usually in tandem with a new feature or major change. No specific format other than a required scope is provided and again the author is requested to use their best judgment to provide context and background for the major change or new scope.
+
+
 How To: Write an Integration
 ============================
 

docs/index.rst

@@ -217,7 +217,6 @@ Indices and tables
     advanced_usage
     benchmarks
     contributing
-    release_note_guidelines
     troubleshooting
     versioning
     upgrading