From 3d5286552600cc8921cd9e4c711b2f52f9c31e85 Mon Sep 17 00:00:00 2001 From: Alan Agius Date: Tue, 12 Oct 2021 08:42:03 +0200 Subject: [PATCH] docs: expand commit message footer description With this change we expand the commit message footer section to include more information about breaking changes and deprecations messages. --- CONTRIBUTING.md | 28 ++++++++++++++++++++++++---- scripts/templates/contributing.ejs | 28 ++++++++++++++++++++++++---- 2 files changed, 48 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7bfb4b3833..bebb81df17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -253,12 +253,32 @@ Just as in the **subject**, use the imperative, present tense: "change" not "cha The body should include the motivation for the change and contrast this with previous behavior. ### Footer -The footer should contain any information about **Breaking Changes** and is also the place to -reference GitHub issues that this commit **Closes**. +The footer can contain information about breaking changes and deprecations. It is also the place to reference GitHub issues, Jira tickets, and other PRs that are related to this commit or that this commit will close. +For example: -**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this. +``` +BREAKING CHANGE: + + + + +Fixes # +``` -A detailed explanation can be found in this [document][commit-message-format]. +or + +``` +DEPRECATED: + + + + +Closes # +``` + +Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions. + +Similarly, a Deprecation section should start with "DEPRECATED: " followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path. ## Signing the CLA diff --git a/scripts/templates/contributing.ejs b/scripts/templates/contributing.ejs index 000afa7620..da62628c12 100644 --- a/scripts/templates/contributing.ejs +++ b/scripts/templates/contributing.ejs @@ -246,12 +246,32 @@ Just as in the **subject**, use the imperative, present tense: "change" not "cha The body should include the motivation for the change and contrast this with previous behavior. ### Footer -The footer should contain any information about **Breaking Changes** and is also the place to -reference GitHub issues that this commit **Closes**. +The footer can contain information about breaking changes and deprecations. It is also the place to reference GitHub issues, Jira tickets, and other PRs that are related to this commit or that this commit will close. +For example: -**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this. +``` +BREAKING CHANGE: + + + + +Fixes # +``` -A detailed explanation can be found in this [document][commit-message-format]. +or + +``` +DEPRECATED: + + + + +Closes # +``` + +Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions. + +Similarly, a Deprecation section should start with "DEPRECATED: " followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path. ## Signing the CLA