[tor-commits] [tor/master] Mention even more about changes files in doc/HACKING

[nickm at torproject.org]

commit cbea334d6ba564c8b251ada832e26211f8172363
Author: Nick Mathewson <nickm at 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!