From 4b36f140ff9dfc24a48712cdbf99ad732418c993 Mon Sep 17 00:00:00 2001 From: Maton Anthony Date: Mon, 6 Nov 2017 21:13:40 +0100 Subject: [PATCH 1/2] doc: request better commit message for breaking changes. Add informations to CONTRIBUTING.md requesting the committers and especially the one working on breaking changes to write proper commits messages containing the reason behind the breaking changes, the case during which it can be triggered, and a description of the breaking change in itself. --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99278a843af683..1718b73cb74559 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -334,6 +334,10 @@ use `Refs:`. - `Refs: http://eslint.org/docs/rules/space-in-parens.html` - `Refs: https://github.com/nodejs/node/pull/3615` +5. If your commit introduce a breaking change (`semver-major`), it should contain +an explanation about the reason of the breaking change, which situation would trigger +the breaking change and what is the exact change. + Sample complete commit message: ```txt @@ -625,6 +629,7 @@ Focus first on the most significant aspects of the change: 1. Does this change make sense for Node.js? 2. Does this change make Node.js better, even if only incrementally? 3. Are there clear bugs or larger scale issues that need attending to? +4. Is the commit message readable and correct? If it contains a breaking change is it clear enough? When changes are necessary, *request* them, do not *demand* them, and do not assume that the submitter already knows how to add a test or run a benchmark. From a0eb036b98cd2f26d49f72e4074c5ea6504a9cad Mon Sep 17 00:00:00 2001 From: Anthony Maton Date: Mon, 6 Nov 2017 22:31:09 +0100 Subject: [PATCH 2/2] doc: fix grammar + add a paragraph regarding breaking change wiki pages - Fix a grammar mispelling - Add a paragraph describing the use and the ideal commit messages. --- CONTRIBUTING.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1718b73cb74559..0d589061d2a65a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -334,10 +334,14 @@ use `Refs:`. - `Refs: http://eslint.org/docs/rules/space-in-parens.html` - `Refs: https://github.com/nodejs/node/pull/3615` -5. If your commit introduce a breaking change (`semver-major`), it should contain +5. If your commit introduces a breaking change (`semver-major`), it should contain an explanation about the reason of the breaking change, which situation would trigger the breaking change and what is the exact change. +Breaking changes will be listed in the wiki with the aim to make upgrading easier. +Please have a look at [Breaking Changes](https://github.com/nodejs/node/wiki/Breaking-changes-between-v4-LTS-and-v6-LTS) +for the level of detail that's suitable. + Sample complete commit message: ```txt