[tor-commits] [tor/master] Coding Standards: Document how to find git commits

[nickm at torproject.org]

commit ac5753d3ca943982290d24899a2c4d406098424a
Author: teor <teor at torproject.org>
Date:   Tue Apr 23 10:03:18 2019 +1000

    Coding Standards: Document how to find git commits
    
    Document how to find git commits and tags for bug fixes in
    CodingStandards.md.
    
    And update some changes file documentation.
    
    Closes ticket 30261.
---
 changes/ticket30261            |  4 ++++
 doc/HACKING/CodingStandards.md | 41 +++++++++++++++++++++++++++++++++++------
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/changes/ticket30261 b/changes/ticket30261
new file mode 100644
index 000000000..e4a2643c8
--- /dev/null
+++ b/changes/ticket30261
@@ -0,0 +1,4 @@
+  o Documentation:
+    - Document how to find git commits and tags for bug fixes in
+      CodingStandards.md. And update some changes file documentation.
+      Closes ticket 30261.
diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md
index 4f229348e..74db2a39a 100644
--- a/doc/HACKING/CodingStandards.md
+++ b/doc/HACKING/CodingStandards.md
@@ -110,12 +110,41 @@ it's a bugfix, mention what bug it fixes and when the bug was
 introduced.  To find out which Git tag the change was introduced in,
 you can use `git describe --contains <sha1 of commit>`.
 
-If at all possible, try to create this file in the same commit where you are
-making the change.  Please give it a distinctive name that no other branch will
-use for the lifetime of your change. To verify the format of the changes file,
-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`.
+If you don't know the commit, you can search the git diffs (-S) for the first
+instance of the feature (--reverse).
+
+For example, for #30224, we wanted to know when the bridge-distribution-request
+feature was introduced into Tor:
+    $ git log -S bridge-distribution-request --reverse
+    commit ebab521525
+    Author: Roger Dingledine <arma at torproject.org>
+    Date:   Sun Nov 13 02:39:16 2016 -0500
+
+        Add new BridgeDistribution config option
+
+    $ git describe --contains ebab521525
+    tor-0.3.2.3-alpha~15^2~4
+
+If you need to know all the Tor versions that contain a commit, use:
+    $ git tag --contains 9f2efd02a1 | sort -V
+    tor-0.2.5.16
+    tor-0.2.8.17
+    tor-0.2.9.14
+    tor-0.2.9.15
+    ...
+    tor-0.3.0.13
+    tor-0.3.1.9
+    tor-0.3.1.10
+    ...
+
+If at all possible, try to create the changes file in the same commit where
+you are making the change.  Please give it a distinctive name that no other
+branch will use for the lifetime of your change. We usually use "ticketNNNNN"
+or "bugNNNNN", where NNNNN is the ticket number. To verify the format of the
+changes file, you can use `make check-changes`.  This is run automatically as
+part of `make check` -- if it fails, we must fix it as soon as possible, so
+that our CI passes.  These checks are implemented in
+`scripts/maint/lintChanges.py`.
 
 Changes file style guide:
   * Changes files begin with "  o Header (subheading):".  The header