commit cbea334d6ba564c8b251ada832e26211f8172363
parent 22e2c3bf7db7f4112e100c4c0529c400f67f09f0
Author: Nick Mathewson <nickm@torproject.org>
Date: Fri, 22 Sep 2017 15:14:36 -0400
Mention even more about changes files in doc/HACKING
Diffstat:
2 files changed, 23 insertions(+), 0 deletions(-)
diff --git 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
@@ -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!
