Skip to content
Snippets Groups Projects

Documentation

Last edited by Alexander Færøy

= About This Document

The following structure is the result of Metrics-Team Brainstorming Session which took place April 14, 2016. A request for comments was posted to the metrics mailing list on the same day. As a last step the document was discussed in the metrics team meeting.

We tried to answer questions using only 50 to 100 words, if possible.

** You are also welcome to edit this page **, correct typos etc. Or, when you don't feel comfortable editing this wiki page or don't know were to put an addition, just add a comment on this #19368 (moved) ticket and we look for a place for the suggestions you have. Same with questions about the document just add a comment or start a discussion [#19368 (moved) on this ticket].

= Metrics-Team Documentation Structure

= General Goals We use the wiki to hold documents related to the Metrics-Team and link them from the team page and the project READMEs. Wiki pages look nicer than text files in Gitweb, but there is still a history of the development available. Wiki edits are open to the public, but will be watched and potentially restricted (e.g., write access exclusively for Metrics-Team), in case random people miss-use these documents.

The documentation should answer questions (new) metrics team members might have. The wiki pages should be the first place to look for answers. The wiki pages can be directly linked from the Metrics-Team page and the README's from projects elsewhere.

We came up with an FAQ page that answers questions and refers to more elaborate documentation where necessary. In addition, we want to provide several Guide documents.

== FAQ Contents Possible frequently asked questions grouped by topic in random order.

=== About the Metrics-Team [=#about]

What projects/products are offered by the M-Team?

The Metrics Team page gives a good first [wiki/org/teams/MetricsTeam#Overview overview] what the team does, which includes "measuring and analyzing things in the public Tor network". For a more concrete hint, take a look at open tickets in Metrics/* components.

Where would I start reading about a code base?

Most metrics-related code bases can be browsed on Tor's Git server. There is no single starting point for reading about them, but text files like README, CONTRIB, or INSTALL might be good first choices.

==== Who maintains the code repositories? There is usually just a single person with push access to a Git repository, and that person should be easy to identify by looking at Git history. If you file a ticket in a Metrics/* component, it will either be auto-assigned to the component owner or reviewed by a metrics team person. And if you're unsure, just ask on IRC who maintains a code base.

==== How do I find out what code bases are maintained and where my contribution would be most valuable? The best answer is to talk to the maintainer before investing much time on preparing a contribution. But if you'd want to start hacking right away, make sure the Git history has recent entries and the ticket you're planning to work on is not ancient.

==== Are there statistics on usage (e.g., how many hits does a service like Atlas or Globe get per day)? There are sanitized server web logs available at https://webstats.torproject.org/, but they're not yet presented in a convenient way that would let you find out how much services are used. This could be your first contribution to make this data set more accessible.

==== Which projects could qualify to be added to the Metrics-Team's projects? There is no clear line dividing projects into metrics projects and others, but some are more related and some are less related. We put more effort on some projects which means includes developer hours and hosting. But even if we don't do that for other projects, they might still be in scope for the metrics team.

==== How do I get involved in metrics team? All metrics-related meetings and discussions happen in public. Please find the details on the metrics team page. Maybe try to find something simple for your first contribution, like an easy bug or small feature, so that we can find out what you're good at. And if you envision an entirely different approach for doing things than we do right now, please come over and discuss that with us, but don't be sad if you're on your own until we're convinced that your approach is really better. For more see our Volunteers Guide.

==== What skills are required for participating? What tools are used? What languages are supported (maybe even in addition to the languages used in a project)? At the core of Tor metrics is data, a lot of data. An important skill would be to know how to learn something useful from data combined with good senses for preserving the privacy of users behind that data. In terms of tools and programming languages, knowing one or two of the following would help: Java, Python, JavaScript, R. As operating system it's useful to know Linux, but feel free to code on any system you like.

==== When and where are team discussions held? See the org/teams/MetricsTeam#Communication page for details, and watch out for announcements/reminders on the team mailing list.

==== Can I write a thesis or do a research project and count on the support of the team? In many cases, yes. We like research, even if we cannot do much research ourselves. If you're doing research using the Tor network data we're providing, that's great! As always, there may be exceptions, but probably not many, and in those cases we should talk. So, yes, get in touch if you're planning to do something cool with Tor network data.

==== Can I expect somebody of the team to comment on my idea, review my code, or run my service? Maybe. It really depends on your idea, code, or service. In many cases we'll be happy to talk to you and spend time on evaluating what you're doing. But we cannot promise that, and "expect" is really a strong word there. We have commitments, and if we look at your idea or code and spend resources on running your service, we might not be working on our commitments at the same time. So, maybe, but not promised.

==== Where are services currently run, and by whom? Regarding the "where", there's a list of current Tor hosts, and regarding the "by whom", take a look at this list of services and operators.

=== Road-map, Features, and Bugs [=#roadmap] This section will also point to the road-map and the release guide.

==== Where can I request a new feature, and when can I expect that to be implemented and deployed? Please file a ticket in the respective Metrics/* subcomponent. And again, "expect" is a strong word here, but you can probably expect it earlier if you submit a patch, even though there's no guarantee that it will be reviewed and applied immediately. Best would be to talk to us first.

==== Where do I find open tickets? There's a list of open tickets in Metrics/* components on the team page.

==== How do I participate in discussions about new features or existing bugs? We try to keep such discussions on Trac tickets, so ideally you would comment there.

==== What are the plans for further developing existing code bases (road-maps)? This road-map & milestones list gives a first impression where development is heading. It provides links to release notes or milestone planning down to single tickets for each milestone.

In some cases we have wiki pages for improvement projects, which are linked from the team page's products section.

How are releases made?

That depends very much on the code base, so please look at the documents there.

How are decisions made about shutting down a service or about removing a feature?

Such decisions are primarily made by operators and maintainers, possibly after consulting the rest of the metrics team.

Who decides about adding a service?

That decision would be made by the prospective operator and by the metrics team after consulting with system administrators.

=== Contribution and Operation [=#contrib] See our Volunteers Guide and the ContributorGuide.

==== How do I submit a patch?

  • The best way is to clone the official repository, add your commits, push to your own repository somewhere, and add a link to the Trac ticket. Second-best way would be to send a commit or series of commits produced by git format-patch. Other ways might also work, but we might ask you to pick a different way that is easier for us to handle. A patch should confirm to the respective style guide.

==== Where do I find official sources? Official sources can be browsed here and cloned as follows: git clone https://git.torproject.org/someproject.git.

==== Where do I find documentation? That depends on the code base, but look out for files called README, CONTRIB, or INSTALL.

==== Are there code style guidelines? Yes, you might find something under Guide Documents here.

==== Which external dependencies are allowed, which are discouraged? We put together some guidelines for deciding about external dependencies here.

==== For people who like to operate a service: how to get started? Depends on the code base, but look out for files called INSTALL in root directories of projects. In any case, reach out to maintainers before attempting to read all code just to get it running. It's their job to write good documentation for operators, and they probably appreciate your questions and feedback.

==== How are patches reviewed? We don't use specific tools for reviewing patches but instead post review results to Trac tickets. Where available, i.e., for Java projects, we use code metrics. Patches have to pass these metrics before we can consider them.

==== Can I help by reviewing code or patches? Yes, for patches, look out for tickets in state "needs_review" in Metrics/* subcomponents. If you want to review an entire code base or portion of it, maybe talk to the developer before starting, to find out whether that code is still used.

==== Can I help by running services, either as backup or primary if Tor does not host one of its services (anymore)? We're currently trying to get more backup instances of services set up, so please talk to us if you'd like to run one of them. Just don't expect it to be easy, because so far we operated all services ourselves and could simply read the code when something went wrong. Regarding primary instances, there's probably a reason why we shut down our instance, so you might be on your own. But feel free to talk to us to find out.

==== What tools are available to ensure that services keep running correctly? We use Nagios to check whether Onionoo works as expected. Other than that, we don't have good scripts yet, but if you want to contribute some good scripts, please don't hesitate.

==== Is there a testing policy? There should be one where we only accept patches that come with tests, but we didn't adhere to such a policy ourselves, so we cannot make that a requirement yet. Please write tests for new code if you can. Or don't complain that our code has bugs.

==== Where can I find tutorials on answering simple questions with e.g. metrics-lib? There are none yet, there's just the Javadocs which may contain some guides for using that library. But if you're into writing good tutorials, we'd happily accept patches.

=== Funding [=#funding] (This probably belongs into a Tor Project's FAQ) This topic's concerns more than just the Metrics-Team. It might belong elsewhere in the Tor Project.

  • Can I get paid for contributing?
  • Not easily, but you should know that many of the currently paid contributors, not limited to the metrics team, started out as unpaid volunteers. We can't promise anything here, but if we spot a good coder with good ideas for making Tor metrics better, we might figure something out.
  • Can I help find funding for something I'd like to work on?
  • It's difficult to give a universal answer here. The reason is that asking for funding is usually done by the project maintainer. Now, if you go find funding for something you'd like to work on, that would likely require some kind of endorsement from Tor that you and your possible contributions are worth funding, and we might not know you enough yet to give you that. Another aspect is that you'll likely need some of our time to review or integrate your work, and we cannot guarantee that without talking about it first. So, please talk to us.
  • Can I bring my own funding, or can I volunteer, and what can I expect from the team in exchange?
  • It's the last part that makes this question difficult. Of course we welcome contributions. But even if a contribution is free, accepting it may not be free. We need to spend time reviewing your work, discussing it with you, integrating it into our code base, and possibly maintaining it in the future. We're happy to consider, but please understand that there's no guarantee that you'll get support from the team.

== Guide Documents [=#guides] Some of the main guide documents were already partially or completely written in some Metrics Projects (like Onionoo or metrics-lib). During the course of writing we noticed that many topics and answers are valid independently of the project. Thus, they should be in a central location. These guide documents are in particular:

Comments

    Please register or sign in to add a comment.