tor-parallel-relay-conn/doc/HACKING/Maintaining.md

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 responsibilities. 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 for that information.

Tor Maintainer

The current maintainer is Nick Mathewson nickm@torproject.org.

The maintainer takes final decisions in terms of engineering, architecture and protocol design. Releasing Tor falls under their responsibility.

Alpha and Master Branches

The Tor repository always has at all times a master branch which contains the upstream ongoing development.

It may also contain 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 responsibility of the stable branch maintainer.

Who

In alphabetical order, the following people have upstream commit access and maintain the following subsystems:

• David Goulet dgoulet@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@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. Regularly 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 maintainer 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.

1. 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.

2. Trivial patches such as comment change, documentation, syntax issues or typos can be merged without a ticket or reviewers.

3. 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.

4. 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.)