Changes

Page history
Apply conversion script to all *.md files. authored by Alexander Hansen Færøy's avatar Alexander Hansen Færøy
Show whitespace changes
Inline Side-by-side
org/teams/MetricsTeam/Documentation.md
View page @ a1a4b621
[[TOC]]
= About This Document = About This Document
...@@ -35,11 +35,11 @@ Possible frequently asked questions grouped by topic in random order. ...@@ -35,11 +35,11 @@ Possible frequently asked questions grouped by topic in random order.
=== About the Metrics-Team [=#about] === About the Metrics-Team [=#about]
==== What projects/products are offered by the M-Team? ==== #### What projects/products are offered by the M-Team?
The [wiki:org/teams/MetricsTeam 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 [wiki:org/teams/MetricsTeam#OpenTickets open tickets in Metrics/* components]. The [Metrics Team page](./org/teams/MetricsTeam) 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](./org/teams/MetricsTeam#OpenTickets).
==== Where would I start reading about a code base? ==== #### Where would I start reading about a code base?
Most metrics-related code bases can be browsed on [https://gitweb.torproject.org/ 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. Most metrics-related code bases can be browsed on [Tor's Git server](https://gitweb.torproject.org/). 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? ==== 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. 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.
...@@ -54,13 +54,13 @@ There are sanitized server web logs available at https://webstats.torproject.org ...@@ -54,13 +54,13 @@ There are sanitized server web logs available at https://webstats.torproject.org
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. 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? ==== How do I get involved in metrics team?
All metrics-related meetings and discussions happen in public. Please find the details on the [wiki:org/teams/MetricsTeam#Communication 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 [wiki:org/teams/MetricsTeam/Volunteers Volunteers Guide]. All metrics-related meetings and discussions happen in public. Please find the details on the [metrics team page](./org/teams/MetricsTeam#Communication). 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](./org/teams/MetricsTeam/Volunteers).
==== 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)? ==== 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. 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? ==== When and where are team discussions held?
See the [wiki:org/teams/MetricsTeam#Communication] page for details, and watch out for announcements/reminders on the team mailing list. See the [org/teams/MetricsTeam#Communication](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? ==== 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. 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.
...@@ -69,7 +69,7 @@ In many cases, yes. We like research, even if we cannot do much research oursel ...@@ -69,7 +69,7 @@ In many cases, yes. We like research, even if we cannot do much research oursel
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. 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? ==== Where are services currently run, and by whom?
Regarding the "where", there's a [https://db.torproject.org/machines.cgi list of current Tor hosts], and regarding the "by whom", take a look at [wiki:org/operations/Infrastructure this list of services and operators]. Regarding the "where", there's a [list of current Tor hosts](https://db.torproject.org/machines.cgi), and regarding the "by whom", take a look at [this list of services and operators](./org/operations/Infrastructure).
=== Road-map, Features, and Bugs [=#roadmap] === Road-map, Features, and Bugs [=#roadmap]
This section will also point to the road-map and the release guide. This section will also point to the road-map and the release guide.
...@@ -78,42 +78,42 @@ This section will also point to the road-map and the release guide. ...@@ -78,42 +78,42 @@ This section will also point to the road-map and the release guide.
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. 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? ==== Where do I find open tickets?
There's a [wiki:org/teams/MetricsTeam#OpenTickets list of open tickets in Metrics/* components] on the team page. There's a [list of open tickets in Metrics/* components](./org/teams/MetricsTeam#OpenTickets) on the team page.
==== How do I participate in discussions about new features or existing bugs? ==== 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. 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)? ==== What are the plans for further developing existing code bases (road-maps)?
This [wiki:org/teams/MetricsTeam#ReleasesandMilestones 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. This [road-map & milestones list](./org/teams/MetricsTeam#ReleasesandMilestones) 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 [wiki:org/teams/MetricsTeam#Products products section]. In some cases we have wiki pages for improvement projects, which are linked from the team page's [products section](./org/teams/MetricsTeam#Products).
==== How are releases made? ==== #### How are releases made?
That depends very much on the code base, so please look at the documents there. 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? ==== #### 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. Such decisions are primarily made by operators and maintainers, possibly after consulting the rest of the metrics team.
==== Who decides about adding a service? ==== #### 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. That decision would be made by the prospective operator and by the metrics team after consulting with system administrators.
=== Contribution and Operation [=#contrib] === Contribution and Operation [=#contrib]
See our [wiki:org/teams/MetricsTeam/Volunteers Volunteers Guide] and the [[ContributorGuide|Contributor Guide]]. See our [Volunteers Guide](./org/teams/MetricsTeam/Volunteers) and the [[ContributorGuide|Contributor Guide]].
==== How do I submit a patch? ==== 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. - 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? ==== Where do I find official sources?
Official sources can be browsed [https://gitweb.torproject.org/ here] and cloned as follows: `git clone https://git.torproject.org/someproject.git`. Official sources can be browsed [here](https://gitweb.torproject.org/) and cloned as follows: `git clone https://git.torproject.org/someproject.git`.
==== Where do I find documentation? ==== Where do I find documentation?
That depends on the code base, but look out for files called `README`, `CONTRIB`, or `INSTALL`. That depends on the code base, but look out for files called `README`, `CONTRIB`, or `INSTALL`.
==== Are there code style guidelines? ==== Are there code style guidelines?
Yes, you might find something under [wiki:org/teams/MetricsTeam/Documentation#GuideDocuments Guide Documents here]. Yes, you might find something under [Guide Documents here](./org/teams/MetricsTeam/Documentation#GuideDocuments).
==== Which external dependencies are allowed, which are discouraged? ==== Which external dependencies are allowed, which are discouraged?
We put together some guidelines for deciding about external dependencies [wiki:org/operations/Guidelines here]. We put together some guidelines for deciding about external dependencies [here](./org/operations/Guidelines).
==== For people who like to operate a service: how to get started? ==== 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. 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.
...@@ -128,7 +128,7 @@ Yes, for patches, look out for tickets in state "needs_review" in Metrics/* subc ...@@ -128,7 +128,7 @@ Yes, for patches, look out for tickets in state "needs_review" in Metrics/* subc
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. 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? ==== What tools are available to ensure that services keep running correctly?
We use Nagios to [https://gitweb.torproject.org/admin/tor-nagios.git/tree/tor-nagios-checks/checks/tor-check-onionoo 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. We use Nagios to [check whether Onionoo works as expected](https://gitweb.torproject.org/admin/tor-nagios.git/tree/tor-nagios-checks/checks/tor-check-onionoo). 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? ==== 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. 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.
...@@ -154,11 +154,11 @@ Some of the main guide documents were already partially or completely written in ...@@ -154,11 +154,11 @@ Some of the main guide documents were already partially or completely written in
During the course of writing we noticed that many topics and answers are valid independently of the project. 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: Thus, they should be in a central location. These guide documents are in particular:
* [[ContributorGuide|Contributor Guide]] and [wiki:org/teams/MetricsTeam/Volunteers Volunteers Guide] * [[ContributorGuide|Contributor Guide]] and [Volunteers Guide](./org/teams/MetricsTeam/Volunteers)
* Coding Style Guides: * Coding Style Guides:
* Metrics Team's [[MetricsJavaStyleGuide|Java Style Guide]] * Metrics Team's [[MetricsJavaStyleGuide|Java Style Guide]]
* The Metrics Team uses the [https://gitweb.torproject.org/tor.git/tree/doc/HACKING/CodingStandards.md Tor C Coding Standards]. * The Metrics Team uses the [Tor C Coding Standards](https://gitweb.torproject.org/tor.git/tree/doc/HACKING/CodingStandards.md).
* Metrics Team's [[MetricsPythonStyleGuide | Python Style Guide]] * Metrics Team's [[MetricsPythonStyleGuide | Python Style Guide]]
* (add more here, when need arises) * (add more here, when need arises)
* Operator Guide docs can be found in the respective code bases and there is a [wiki:org/teams/MetricsTeam/Operation wiki section for mirror operators]. * Operator Guide docs can be found in the respective code bases and there is a [wiki section for mirror operators](./org/teams/MetricsTeam/Operation).