From 197051f2f0c2cbd309089b96bacbe5599c3f71d6 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Tue, 4 Aug 2020 10:03:49 -0400 Subject: [PATCH] update contrib --- CONTRIBUTING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9d9e99fef..c6b67574a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,6 +90,19 @@ To pull in updates from the origin repo, run Every non-trivial PR must update the [CHANGELOG.md]. +The Changelog is *not* a record of what Pull Requests were merged; +the commit history already shows that. The Changelog is a notice to the user +about how their expectations of the software should be modified. +It is part of the UX of a release and is a *critical* user facing integration point. +The Changelog must be clean, inviting, and readable, with concise, meaningful entries. +Entries must be semantically meaningful to users. If a change takes multiple +Pull Requests to complete, it should likely have only a single entry in the +Changelog describing the net effect to the user. + +When writing Changelog entries, ensure they are targeting users of the software, +not fellow developers. Developers have much more context and care about more +things than users do. Changelogs are for users. + Changelog structure is modeled after [Tendermint Core](https://github.com/tendermint/tendermint/blob/master/CHANGELOG.md) @@ -101,9 +114,11 @@ Changes for a given release should be split between the five sections: Security, Changes, Features, Improvements, Bug Fixes. Changelog entries should be formatted as follows: + ``` - [pkg] \#xxx Some description about the change (@contributor) ``` + Here, `pkg` is the part of the code that changed (typically a top-level crate, but could be /), `xxx` is the pull-request number, and `contributor` is the author/s of the change.