Skip to content
Snippets Groups Projects

TorOnTrac

Last edited by Alexander Færøy

How Tor uses trac tickets

This page describes how we use Trac tickets for the little-t Tor software (Core Tor/Tor). Other components can decide that they want to follow the same process, or do something else.

Milestone

This is critical. We use these milestones:

  • Tor 0.x.y.z-final For tickets that we want to merge into the 0.x.y.z series. If 0.x.y.z is in alpha, this includes stuff under active development. If 0.x.y.z is stable, this should only include backports.

  • Tor: Unspecified For tickets that we would like to do quite soon, given infinite knowledge and resources. For most of these tickets, we could merge a good patch into the current development branch if somebody writes one. We might do one ourselves some day.

  • Tor: Very Long Term For tickets that will require deep architectural changes to Tor that we don't understand well enough to plan when we might make them; for tickets of uncertain benefit and great difficulty; for tickets we've got no plans to do any time soon for some other reason.

Triage

Once in a while, we'll do a triage for a specific milestone. If a ticket is triaged out, this keyword will be added to it:

  • triage-out-{series}-{date} Where series is the version of the milestone that the ticket is being removed from (ex: 030). date is the year and month of when the triage occurred with format YYYYMM

Keywords

This is a free-form field, so use any extra keywords that you think will be helpful. Commonly used ones are:

  • {username}-patch The user called username on trac wrote this patch. Mainly, we use this for developers who write a lot of patches, so that it's easy to say "show me everything where I wrote the patch here" or "show me everything in needs_review where I didn't write the patch."

  • Tor subsystems. Describes the parts of Tor most affected by this ticket.

  • tor-client: Client functionalities.

  • tor-relay: Everything related to being a relay.

  • tor-hs: Hidden/Onion service.

  • tor-dirauth: For changes to little-t-tor related to Directory Authorities.

  • tor-bwauth: Anything related to bwauth.

  • tor-pt: Pluggable Transport.

  • tor-guard: Everything related to Guard code.

  • tor-bridge: Bridge

  • tor-sr: Shared random.

  • tor-log: Everything related to logging

  • tor-doc: Everything related to documentation (comments, man page, doc/; previously just doc?)

  • tor-control: Anything related to the control port.

  • tor-sandbox: Related to sandboxing of "tor".

  • tor-crypto: Crypto subsystem.

  • tor-dns: Anything related to DNS subsystem or resolving address.

  • tor-sched: Scheduler related (usually in scheduler.c and cie).

  • tor-cmux: Circuit multiplexing (circuitmux.c and cie).

  • Ease-of-task keywords

  • "points <= .1" (not a keyword): it will take less than an hour, if you know how.

  • easy: it wouldn't be very hard for a developer with no previous Tor experience

  • intro: it's a good introduction to the tor codebase, but it might not be so easy (e.g., might touch a lot of things in a not-too-complicated way).

  • term-project: it's a good subject for an undergraduate term project or a GSoC student.

  • research-program: it's a good topic for several papers, or a dissertation, or something like that.

  • Security keywords:

    • '''sec-dos''': Denial of Service
    • '''sec-hardening''':
    • '''sec-trove''': Ticket associated with a TROVE
    • '''sec-''' (let's try to list the one we want)

  • Rust keywords:

    • '''rust-pilot''': Tasks before we determine if Rust can be a first-class language in tor
    • '''rust''': tor-related tickets requiring rust knowledge

  • Specification (and proposal) keywords:

  • tor-spec About bugs or changes in the specifications (tor-spec.git, etc.; previously just spec?)

  • propXXX: This ticket implements (part of) proposal XXX

  • needs-proposal: The work of the ticket needs a proposal.

  • Testing keywords: (WIP)

    • '''test'''
    • '''test-coverage'''
    • '''test-fuzzing'''
    • '''test-unit'''
    • '''test-integration'''

  • What this ticket is about?

    • '''regression''': This ticket is a possible regression.
    • '''refactor''': This ticket is about refactoring some Tor code.
    • '''technical-debt''': This ticket is about technical debt.
    • '''performance'''

  • Planning keywords:

    • maybe we should have some way to indicate "this is deferrable", "this is in", "this is out" as we do triage... but they should not stick around forever.
    • '''{series}-deferrable''' This ticket can be safely deferred from ''series'', though it would be nice to do. (''Series'' here or elsewhere is a version number without periods or final number, such as "025" or "026".)
    • '''{series}-backport''': where ''series'' is the version eg. 030-backport.
    • '''lorax''': There is no plan to fix this, but we'd be happy to take a good patch for it if someone else cares enough to write one. (''"Unless someone like you cares a whole awful lot / Nothing is going to get better. It's not!"'' -Dr. Seuss, ''The Lorax'')

Priority

We don't have a consistent way to set this. I would prefer that we get one some time.

Owner

We use this field for when a person is working on the ticket.

Points

  • points: this is the estimation (in days) for how long will take to complete the ticket.
  • actual points: this is the amount of days that took to complete the ticket. We fill it when we close the ticket.

Status

We use this field to described what is the status of the ticket:

* '''new''': this is a new ticket and nobody is working on it.
* '''assigned''': this ticket has been reclaimed and 'owner' is working on it.
* '''needs_information''': we need more information to complete this ticket
* '''needs_revision''': needs to check if the ticket has been completed
* '''needs_review''': this ticket needs somebody to do the code review
* '''merge_ready''': the code from this ticket is ready to be merged
* '''closed''': the ticket is being closed (implemented or not)
* '''reopened''': reopening the ticket

Version

This can be the version in which a bug first occurred, but more typically it is the version in which the bug was noticed.

Component

Is Core Tor/Tor.

Subcomponents:

* '''DirAuth''': tasks for directory auth operators. 
* '''sbws''': tasks for sbws software
* '''sbws-doc''': Everything related to documentation in sbws (to do not confuse with '''tor-doc''').

Sponsor Work

We use the sponsor field to indicate the sponsor (if any) that may be supporting the completion of the ticket. For Core Tor/Tor you can find who is sponsoring its deployment in the bottom of the network team's wiki page.

Comments

    Please register or sign in to add a comment.