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-<whatever>''' (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
* '''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 [wiki:org/teams/NetworkTeam#ActiveSponsors network team's wiki page].
