[tor-commits] [tor/master] doc: Add Maintaining.md documentation

[nickm at torproject.org]

commit 91748cd17c1c1c2d5590d3b5533b74fcc1cd2140
Author: David Goulet <dgoulet at torproject.org>
Date:   Mon Oct 29 08:58:19 2018 -0400

    doc: Add Maintaining.md documentation
    
    Closes #28225
    
    Signed-off-by: David Goulet <dgoulet at torproject.org>
---
 doc/HACKING/Maintaining.md | 113 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)

diff --git a/doc/HACKING/Maintaining.md b/doc/HACKING/Maintaining.md
new file mode 100644
index 000000000..22d62b547
--- /dev/null
+++ b/doc/HACKING/Maintaining.md
@@ -0,0 +1,113 @@
+# Maintaining Tor
+
+This document details the duties and processes on maintaining the Tor code
+base.
+
+The first section describes who is the current Tor maintainer and what are the
+responsabilities. Tor has one main single maintainer but does have many
+committers and subsystem maintainers.
+
+The second third section describes how the **alpha and master** branches are
+maintained and by whom.
+
+Finally, the last section describes how the **stable** branches are maintained
+and by whom.
+
+This document does not cover how Tor is released, please see
+[ReleasingTor.md](ReleasingTor.md) for that information.
+
+## Tor Maintainer
+
+The current maintainer is Nick Mathewson <nickm at torproject.org>.
+
+The maintainer takes final decisions in terms of engineering, architecture and
+protocol design. Releasing Tor falls under their responsability.
+
+## Alpha and Master Branches
+
+The Tor repository always has at all time a **master** branch which contains
+the upstream ongoing development.
+
+It may also contains a branch for a released feature freezed version which is
+called the **alpha** branch. The git tag and version number is always
+postfixed with `-alpha[-dev]`. For example: `tor-0.3.5.0-alpha-dev` or
+`tor-0.3.5.3-alpha`.
+
+Tor is separated into subsystems and some of those are maintained by other
+developers than the main maintainer. Those people have commit access to the
+code base but only commit (in most cases) into the subsystem they maintain.
+
+Upstream merges are restricted to the alpha and master branches. Subsystem
+maintainers should never push a patch into a stable branch which is the
+responsability of the [stable branch maintainer](#stable-branches).
+
+### Who
+
+In alphabetical order, the following people have upstream commit access and
+maintain the following subsystems:
+
+- David Goulet <dgoulet at torproject.org>
+  * Onion Service (including Shared Random).  
+    ***keywords:*** *[tor-hs]*
+  * Channels, Circuitmux, Connection, Scheduler.  
+    ***keywords:*** *[tor-chan, tor-cmux, tor-sched, tor-conn]*
+  * Cell Logic (Handling/Parsing).  
+    ***keywords:*** *[tor-cell]*
+  * Threading backend.
+    ***keywords:*** *[tor-thread]*  
+
+- George Kadianakis <asn at torproject.org>
+  * Onion Service (including Shared Random).  
+    ***keywords:*** *[tor-hs]*
+  * Guard.  
+    ***keywords:*** *[tor-guard]*
+  * Pluggable Transport (excluding Bridge networking).  
+    ***keywords:*** *[tor-pt]*
+
+### Tasks
+
+These are the tasks of a subsystem maintainer:
+
+1. Regurlarly go over `merge_ready` tickets relevant to the related subsystem
+   and for the current alpha or development (master branch) Milestone.
+
+2. A subsystem maintainer is expected to contribute to any design changes
+   (including proposals) or large patch set about the subsystem.
+
+3. Leave their ego at the door. Mistakes will be made but they have to be
+   taking care of seriously. Learn and move on quickly.
+
+### Merging Policy
+
+These are few important items to follow when merging code upstream:
+
+1. To merge code upstream, the patch must have passed our CI (currently
+   github.com/torproject), have a corresponding ticket and reviewed by
+   **at least** one person that is not the original coder.
+
+   Example A: If Alice writes a patch then Bob, a Tor network team member,
+   reviews it and flags it `merge_ready`. Then, the maintainter is required
+   to look at the patch and makes a decision.
+
+   Example B: If the maintainer writes a patch then Bob, a Tor network
+   team member, reviews it and flags it `merge_ready`, then the maintainer
+   can merge the code upstream.
+
+2. Maintainer makes sure the commit message should describe what was fixed
+   and, if it applies, how was it fixed. It should also always refer to
+   the ticket number.
+
+3. Trivial patches such as comment change, documentation, syntax issues or
+   typos can be merged without a ticket or reviewers.
+
+4. Tor uses the "merge forward" method that is if a patch applies to the
+   alpha branch, it has to be merged there first and then merged forward
+   into master.
+
+5. Maintainer should always consult with the network team about any doubts,
+   mis-understandings or unknowns of a patch. Final word will always go to the
+   main Tor maintainer.
+
+## Stable Branches
+
+(Currently being drafted and reviewed by the network team.)