From e6ab3ecf3307858afcc19026502873bacad4984f Mon Sep 17 00:00:00 2001 From: Yun Kim Date: Tue, 15 Nov 2022 14:09:34 -0500 Subject: [PATCH 1/6] Documentation for release note guidelines and new reno template --- README.md | 9 +- docs/index.rst | 1 + docs/release_note_guidelines.rst | 186 ++++++++++++++++++++++++ releasenotes/template-release-note.yaml | 21 +++ 4 files changed, 211 insertions(+), 6 deletions(-) create mode 100644 docs/release_note_guidelines.rst create mode 100644 releasenotes/template-release-note.yaml diff --git a/README.md b/README.md index d351c24c4e3..0f09d9942c4 100644 --- a/README.md +++ b/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 - -Document the changes in the generated file, remove the irrelevant sections and -commit the release note with the change. +See the [release note guidelines](https://ddtrace.readthedocs.io/en/stable/release_note_guidelines.html) for +instructions on generating, writing, formatting, and styling release notes. diff --git a/docs/index.rst b/docs/index.rst index 6aaa35b246b..c663f379dad 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -217,6 +217,7 @@ Indices and tables advanced_usage benchmarks contributing + release_note_guidelines troubleshooting versioning upgrading diff --git a/docs/release_note_guidelines.rst b/docs/release_note_guidelines.rst new file mode 100644 index 00000000000..130ed15c074 --- /dev/null +++ b/docs/release_note_guidelines.rst @@ -0,0 +1,186 @@ +Release Note Guidelines +======================= +The guidelines below describe how to ensure consistency and clarity in release notes. + +Release notes are the first product documentation a user will see when updating the library. Therefore, we must take care to ensure the quality of release notes. + +For every pull request that changes how a user interacts with the library, a pull request should include a release note entry. + + +Does the change require a release note? ++++++++++++++++++++++++++++++++++++++++ + +A release note is required if a PR is user-facing, 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. In these cases, the pull request must be labelled ``changelog/no-changelog``. +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) + +How to Generate a Release Note +++++++++++++++++++++++++++++++ +Release notes are generated with the command line tool [reno](https://docs.openstack.org/reno/latest/user/usage.html#creating-new-release-notes) +which can be used with riot:: + + $ riot run reno new + +The is used as the prefix for a new file created in ``releasenotes/notes``. +The is used internally and is not visible in the the product documentation. + +The format of the must be: +- number of words should not exceed 5 +- words are separated with hyphens +- lowercase + +For example: +- fix-aioredis-catch-cancellederror +- deprecate-tracer-writer +- add-graphene-support +- internalize-ddtrace-utils + +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. +Example:: + + features: + - | + graphene: Adds support for ``graphene>=2``. `See the graphql documentation `_ + 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. +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. +Example:: + + deprecations: + - | + tracing: ``ddtrace.Span.meta`` has been deprecated. Use ``ddtrace.Span.get_tag`` and ``ddtrace.Span.set_tag`` instead. + +Fixes: Bug fixes. +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, which should not happen often. +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. +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:: + + --- +
: + - | + scope: note + +Scope +~~~~~ + +This is a one-word scope shared between the release note and the conventional commit format used +in the pull request title. This should 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:: + + : This introduces . + +- Upgrade: Use present tense with the following formats:: + + : This upgrades . With this upgrade, . + : has been removed. As an alternative to , you can use instead. + +- Deprecations: Use present tense for when deprecation/removal actually happens and future tense for +when deprecation/removal is planned to happen. Include deprecation/removal timeline, +as well as workarounds and alternatives in the following format:: + + : is deprecated and will be removed in . As an alternative to , you can use instead. + +- Fixes: Use past tense for the problem and present tense for the fix and solution in the following format:: + + : This fix resolves an issue where caused . + +- 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 judgement 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 judgement to provide context and background +for the major change or new scope. + +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 will be used multiple times in a release note, 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. + diff --git a/releasenotes/template-release-note.yaml b/releasenotes/template-release-note.yaml new file mode 100644 index 00000000000..4b6d34b52d0 --- /dev/null +++ b/releasenotes/template-release-note.yaml @@ -0,0 +1,21 @@ +--- +prelude: > + : . +features: + - | + : this introduces . +upgrade: + - | + : this upgrades . With this upgrade, you can . + - | + : has been removed. As an alternative to , you can use instead. +deprecations: + - | + : is deprecated and will be removed in . + As an alternative to , you can use instead. +fixes: + - | + : this fix resolves an issue where caused . +other: + - | + : . From c5e6d1844a2cca055195cb6b906785046f63d622 Mon Sep 17 00:00:00 2001 From: Yun Kim Date: Tue, 15 Nov 2022 15:06:58 -0500 Subject: [PATCH 2/6] Move release note guidelines docs to contributing docs --- .github/PULL_REQUEST_TEMPLATE.md | 3 +- README.md | 2 +- docs/contributing.rst | 170 ++++++++++++++++++++++ docs/index.rst | 1 - docs/release_note_guidelines.rst | 186 ------------------------ releasenotes/template-release-note.yaml | 6 +- 6 files changed, 176 insertions(+), 192 deletions(-) delete mode 100644 docs/release_note_guidelines.rst diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5af18b1424a..8cc77a451e1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,6 +4,7 @@ ## 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. diff --git a/README.md b/README.md index 0f09d9942c4..b5b5a4a72fd 100644 --- a/README.md +++ b/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. diff --git a/docs/contributing.rst b/docs/contributing.rst index da46e4a726c..8fa4e1143de 100644 --- a/docs/contributing.rst +++ b/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 `_ +* 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 + +The is used as the prefix for a new file created in ``releasenotes/notes``. +The is used internally and is not visible in the the product documentation. + +Generally, the format of the ```` 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 `_ + 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:: + + --- +
: + - | + 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:: + + : This introduces . + +* Upgrade: Use present tense with the following formats (upgrade or removal respectively):: + + : This upgrades . With this upgrade, . + : has been removed. As an alternative to , you can use 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:: + + : is deprecated and will be removed in . As an alternative to , you can use instead. + +* Fixes: Use past tense for the problem and present tense for the fix and solution in the following format:: + + : This fix resolves an issue where caused . + +* 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 ============================ diff --git a/docs/index.rst b/docs/index.rst index c663f379dad..6aaa35b246b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -217,7 +217,6 @@ Indices and tables advanced_usage benchmarks contributing - release_note_guidelines troubleshooting versioning upgrading diff --git a/docs/release_note_guidelines.rst b/docs/release_note_guidelines.rst deleted file mode 100644 index 130ed15c074..00000000000 --- a/docs/release_note_guidelines.rst +++ /dev/null @@ -1,186 +0,0 @@ -Release Note Guidelines -======================= -The guidelines below describe how to ensure consistency and clarity in release notes. - -Release notes are the first product documentation a user will see when updating the library. Therefore, we must take care to ensure the quality of release notes. - -For every pull request that changes how a user interacts with the library, a pull request should include a release note entry. - - -Does the change require a release note? -+++++++++++++++++++++++++++++++++++++++ - -A release note is required if a PR is user-facing, 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. In these cases, the pull request must be labelled ``changelog/no-changelog``. -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) - -How to Generate a Release Note -++++++++++++++++++++++++++++++ -Release notes are generated with the command line tool [reno](https://docs.openstack.org/reno/latest/user/usage.html#creating-new-release-notes) -which can be used with riot:: - - $ riot run reno new - -The is used as the prefix for a new file created in ``releasenotes/notes``. -The is used internally and is not visible in the the product documentation. - -The format of the must be: -- number of words should not exceed 5 -- words are separated with hyphens -- lowercase - -For example: -- fix-aioredis-catch-cancellederror -- deprecate-tracer-writer -- add-graphene-support -- internalize-ddtrace-utils - -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. -Example:: - - features: - - | - graphene: Adds support for ``graphene>=2``. `See the graphql documentation `_ - 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. -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. -Example:: - - deprecations: - - | - tracing: ``ddtrace.Span.meta`` has been deprecated. Use ``ddtrace.Span.get_tag`` and ``ddtrace.Span.set_tag`` instead. - -Fixes: Bug fixes. -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, which should not happen often. -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. -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:: - - --- -
: - - | - scope: note - -Scope -~~~~~ - -This is a one-word scope shared between the release note and the conventional commit format used -in the pull request title. This should 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:: - - : This introduces . - -- Upgrade: Use present tense with the following formats:: - - : This upgrades . With this upgrade, . - : has been removed. As an alternative to , you can use instead. - -- Deprecations: Use present tense for when deprecation/removal actually happens and future tense for -when deprecation/removal is planned to happen. Include deprecation/removal timeline, -as well as workarounds and alternatives in the following format:: - - : is deprecated and will be removed in . As an alternative to , you can use instead. - -- Fixes: Use past tense for the problem and present tense for the fix and solution in the following format:: - - : This fix resolves an issue where caused . - -- 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 judgement 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 judgement to provide context and background -for the major change or new scope. - -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 will be used multiple times in a release note, 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. - diff --git a/releasenotes/template-release-note.yaml b/releasenotes/template-release-note.yaml index 4b6d34b52d0..897b7fbf6e3 100644 --- a/releasenotes/template-release-note.yaml +++ b/releasenotes/template-release-note.yaml @@ -3,10 +3,10 @@ prelude: > : . features: - | - : this introduces . + : This introduces . upgrade: - | - : this upgrades . With this upgrade, you can . + : This upgrades . With this upgrade, you can . - | : has been removed. As an alternative to , you can use instead. deprecations: @@ -15,7 +15,7 @@ deprecations: As an alternative to , you can use instead. fixes: - | - : this fix resolves an issue where caused . + : This fix resolves an issue where caused . other: - | : . From 960fbea9a328463c534c44e26701386334576aea Mon Sep 17 00:00:00 2001 From: Yun Kim Date: Tue, 15 Nov 2022 17:49:24 -0500 Subject: [PATCH 3/6] Move instructions to template release note --- docs/contributing.rst | 29 +++---------------------- releasenotes/template-release-note.yaml | 11 +++++++++- 2 files changed, 13 insertions(+), 27 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 8fa4e1143de..0708fc70000 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -46,10 +46,8 @@ a human. All code style enforcement must be automated to avoid bikeshedding and losing time. -Release Note Guidelines +Release Notes ======================= -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. @@ -192,29 +190,8 @@ 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:: - - : This introduces . - -* Upgrade: Use present tense with the following formats (upgrade or removal respectively):: - - : This upgrades . With this upgrade, . - : has been removed. As an alternative to , you can use 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:: - - : is deprecated and will be removed in . As an alternative to , you can use instead. - -* Fixes: Use past tense for the problem and present tense for the fix and solution in the following format:: - - : This fix resolves an issue where caused . - -* 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. - +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 ============================ diff --git a/releasenotes/template-release-note.yaml b/releasenotes/template-release-note.yaml index 897b7fbf6e3..ea04aeabd56 100644 --- a/releasenotes/template-release-note.yaml +++ b/releasenotes/template-release-note.yaml @@ -1,21 +1,30 @@ --- 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. : . features: - | - : This introduces . + Use present tense with the following format: + : This introduces . Use present tense here. upgrade: - | + Use present tense with the following formats, respectively for enhancements or removals: : This upgrades . With this upgrade, you can . - | : has been removed. As an alternative to , you can use 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: : is deprecated and will be removed in . As an alternative to , you can use instead. fixes: - | + Use past tense for the problem and present tense for the fix and solution in the following format: : This fix resolves an issue where caused . 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. : . From 2cae6c4c8d685ce26f1773f388ba9ba9132db57b Mon Sep 17 00:00:00 2001 From: Yun Kim Date: Wed, 16 Nov 2022 10:06:29 -0500 Subject: [PATCH 4/6] Add instructions to template. --- docs/contributing.rst | 3 ++- releasenotes/template-release-note.yaml | 11 ++++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 0708fc70000..85613e38771 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -85,6 +85,7 @@ Release notes should: * 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. Release notes should not: @@ -189,7 +190,7 @@ To ensure consistency in component naming, the convention in referring to compon Note ~~~~ -The note is a brief description of the change. It should follow sentence-case capitalization. +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. diff --git a/releasenotes/template-release-note.yaml b/releasenotes/template-release-note.yaml index ea04aeabd56..5f533536a97 100644 --- a/releasenotes/template-release-note.yaml +++ b/releasenotes/template-release-note.yaml @@ -5,26 +5,31 @@ prelude: > : . features: - | - Use present tense with the following format: + For new features such as a new integration or component. Use present tense with the following format: : This introduces . Use present tense here. 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: : This upgrades . With this upgrade, you can . - | : has been removed. As an alternative to , you can use 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: : is deprecated and will be removed in . As an alternative to , you can use instead. fixes: - | + For reporting bug fixes. Use past tense for the problem and present tense for the fix and solution in the following format: : This fix resolves an issue where caused . 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. + 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. : . From b2e8e997b2d6ebf81f1a7b63df6d885fea1f1a50 Mon Sep 17 00:00:00 2001 From: Yun Kim Date: Wed, 16 Nov 2022 13:24:38 -0500 Subject: [PATCH 5/6] Add guidelines to template release note --- docs/contributing.rst | 33 +++++++++++--------- releasenotes/template-release-note.yaml | 41 ++++++++++++++++++++----- 2 files changed, 52 insertions(+), 22 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 85613e38771..c4bafe74d4c 100644 --- a/docs/contributing.rst +++ b/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,21 +78,26 @@ 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 +++++++++++++++++++++++++ @@ -100,15 +105,15 @@ Release notes are generated with the command line tool ``reno`` which can be use $ riot run reno new -The is used as the prefix for a new file created in ``releasenotes/notes``. -The is used internally and is not visible in the the product documentation. +The ```` is used as the prefix for a new file created in ``releasenotes/notes``. +The ```` is used internally and is not visible in the the product documentation. Generally, the format of the ```` 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 +++++++++++++++++++++ diff --git a/releasenotes/template-release-note.yaml b/releasenotes/template-release-note.yaml index 5f533536a97..dd5457d6751 100644 --- a/releasenotes/template-release-note.yaml +++ b/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. - : . + Format: : . features: - | For new features such as a new integration or component. Use present tense with the following format: - : This introduces . Use present tense here. + Format: : This introduces . 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: - : This upgrades . With this upgrade, you can . + Format: : This upgrades . With this upgrade, you can . - | - : has been removed. As an alternative to , you can use instead. + Format: : is now removed. As an alternative to , you can use 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: - : is deprecated and will be removed in . - As an alternative to , you can use instead. + Format: : is deprecated and will be removed in . + As an alternative to , you can use instead. fixes: - | For reporting bug fixes. Use past tense for the problem and present tense for the fix and solution in the following format: - : This fix resolves an issue where caused . + Format: : This fix resolves an issue where caused . 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: : . From 8984a649d0f42b74b46ada4203c13e628e5c3880 Mon Sep 17 00:00:00 2001 From: Yun Kim Date: Wed, 16 Nov 2022 18:49:59 -0500 Subject: [PATCH 6/6] Fix capitalization --- docs/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index c4bafe74d4c..f48d015934a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -157,7 +157,7 @@ Once finished, the release note should be committed with the rest of the changes * 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 + 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 @@ -187,8 +187,8 @@ To ensure consistency in component naming, the convention in referring to compon * Tracer: ``tracing`` * Profiler: ``profiling`` -* Application security monitoring: ``ASM`` -* Dynamic instrumentation: ``dynamic instrumentation`` +* Application Security Monitoring: ``ASM`` +* Dynamic Instrumentation: ``dynamic instrumentation`` * CI Visibility: ``CI visibility`` * Integrations: ``integration_name``