commit cbea334d6ba564c8b251ada832e26211f8172363 Author: Nick Mathewson <nickm@torproject.org> Date: Fri Sep 22 15:14:36 2017 -0400 Mention even more about changes files in doc/HACKING --- doc/HACKING/CodingStandards.md | 20 ++++++++++++++++++++ doc/HACKING/HowToReview.md | 3 +++ 2 files changed, 23 insertions(+) diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 2980b775f..dd21d6fd2 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -100,6 +100,26 @@ you can use `make check-changes`. This is run automatically as part of `make check` -- if it fails, we must fix it before we release. These checks are implemented in `scripts/maint/lintChanges.py`. +Changes file style guide: + * Changes files begin with " o Header (subheading):". The header + should usually be "Minor/Major bugfixes/features". The subheading is a + particular area within Tor. See the ChangeLog for examples. + + * Make everything terse. + + * Write from the user's point of view: describe the user-visible changes + right away. + + * Mention configuration options by name. If they're rare or unusual, + remind people what they're for. + + * Describe changes in the present tense and in the imperative: not past. + + * Every bugfix should have a sentence of the form "Fixes bug 1234; bugfix + on 0.1.2.3-alpha", describing what bug was fixed and where it came from. + + * "Relays", not "servers", "nodes", or "Tor relays". + When we go to make a release, we will concatenate all the entries in changes to make a draft changelog, and clear the directory. We'll then edit the draft changelog into a nice readable format. diff --git a/doc/HACKING/HowToReview.md b/doc/HACKING/HowToReview.md index d53318942..2d1f3d1c9 100644 --- a/doc/HACKING/HowToReview.md +++ b/doc/HACKING/HowToReview.md @@ -19,6 +19,8 @@ Top-level smell-checks - Does `make check-spaces` pass? +- Does `make check-changes` pass? + - Does it have a reasonable amount of tests? Do they pass? Do they leak memory? @@ -32,6 +34,7 @@ Top-level smell-checks - If this changes Tor's behavior on the wire, is there a design proposal? +- If this changes anything in the code, is there a "changes" file? Let's look at the code!