doc/HACKING/Maintaining.md

   1 # Maintaining Tor
   2
   3 This document details the duties and processes on maintaining the Tor code
   4 base.
   5
   6 The first section describes who is the current Tor maintainer and what are the
   7 responsibilities. Tor has one main single maintainer but does have many
   8 committers and subsystem maintainers.
   9
  10 The second third section describes how the **alpha and main** branches are
  11 maintained and by whom.
  12
  13 Finally, the last section describes how the **stable** branches are maintained
  14 and by whom.
  15
  16 This document does not cover how Tor is released, please see
  17 [ReleasingTor.md](ReleasingTor.md) for that information.
  18
  19 ## Tor Maintainer
  20
  21 The current maintainer is Nick Mathewson <nickm@torproject.org>.
  22
  23 The maintainer takes final decisions in terms of engineering, architecture and
  24 protocol design. Releasing Tor falls under their responsibility.
  25
  26 ## Alpha and Master Branches
  27
  28 The Tor repository always has at all times a **main** branch which contains
  29 the upstream ongoing development.
  30
  31 It may also contain a branch for a released feature freezed version which is
  32 called the **alpha** branch. The git tag and version number is always
  33 postfixed with `-alpha[-dev]`. For example: `tor-0.3.5.0-alpha-dev` or
  34 `tor-0.3.5.3-alpha`.
  35
  36 Tor is separated into subsystems and some of those are maintained by other
  37 developers than the main maintainer. Those people have commit access to the
  38 code base but only commit (in most cases) into the subsystem they maintain.
  39
  40 Upstream merges are restricted to the alpha and main branches. Subsystem
  41 maintainers should never push a patch into a stable branch which is the
  42 responsibility of the [stable branch maintainer](#stable-branches).
  43
  44 ### Who
  45
  46 In alphabetical order, the following people have upstream commit access and
  47 maintain the following subsystems:
  48
  49 - David Goulet <dgoulet@torproject.org>
  50   * Onion Service (including Shared Random).
  51     ***keywords:*** *[tor-hs]*
  52   * Channels, Circuitmux, Connection, Scheduler.
  53     ***keywords:*** *[tor-chan, tor-cmux, tor-sched, tor-conn]*
  54   * Cell Logic (Handling/Parsing).
  55     ***keywords:*** *[tor-cell]*
  56   * Threading backend.
  57     ***keywords:*** *[tor-thread]*
  58
  59 - George Kadianakis <asn@torproject.org>
  60   * Onion Service (including Shared Random).
  61     ***keywords:*** *[tor-hs]*
  62   * Guard.
  63     ***keywords:*** *[tor-guard]*
  64   * Pluggable Transport (excluding Bridge networking).
  65     ***keywords:*** *[tor-pt]*
  66
  67 ### Tasks
  68
  69 These are the tasks of a subsystem maintainer:
  70
  71 1. Regularly go over `merge_ready` tickets relevant to the related subsystem
  72    and for the current alpha or development (main branch) Milestone.
  73
  74 2. A subsystem maintainer is expected to contribute to any design changes
  75    (including proposals) or large patch set about the subsystem.
  76
  77 3. Leave their ego at the door. Mistakes will be made but they have to be
  78    taking care of seriously. Learn and move on quickly.
  79
  80 ### Merging Policy
  81
  82 These are few important items to follow when merging code upstream:
  83
  84 1. To merge code upstream, the patch must have passed our CI (currently
  85    github.com/torproject), have a corresponding ticket and reviewed by
  86    **at least** one person that is not the original coder.
  87
  88    Example A: If Alice writes a patch then Bob, a Tor network team member,
  89    reviews it and flags it `merge_ready`. Then, the maintainer is required
  90    to look at the patch and makes a decision.
  91
  92    Example B: If the maintainer writes a patch then Bob, a Tor network
  93    team member, reviews it and flags it `merge_ready`, then the maintainer
  94    can merge the code upstream.
  95
  96 2. Maintainer makes sure the commit message should describe what was fixed
  97    and, if it applies, how was it fixed. It should also always refer to
  98    the ticket number.
  99
 100 3. Trivial patches such as comment change, documentation, syntax issues or
 101    typos can be merged without a ticket or reviewers.
 102
 103 4. Tor uses the "merge forward" method, that is, if a patch applies to the
 104    alpha branch, it has to be merged there first and then merged forward
 105    into main.
 106
 107 5. Maintainer should always consult with the network team about any doubts,
 108    mis-understandings or unknowns of a patch. Final word will always go to the
 109    main Tor maintainer.
 110
 111 ## Stable Branches
 112
 113 (Currently being drafted and reviewed by the network team.)