[metrics-team] Blog post about contributing to the Tor metrics timeline

Tue Feb 23 21:21:39 UTC 2021

On 2/23/21 6:15 PM, David Fifield wrote:
> I want to make a blog post explaining how to contribute to the metrics
> timeline. By this, I hope to attract new people to working with Tor
> Metrics and helping maintain the timeline. This is a draft of the post I
> hope to make.
> 
> - The timeline used to be imported into the Tor Metrics site so that a
>   table of events could be displayed below graphs. From
>   https://metrics.torproject.org/news.html, it looks like the timeline
>   has not been imported since December 2020. I presume this is because
>   Karsten used to do it himself.
> - Is is all right to recommend that people contact the metrics team if
>   they have trouble registering an account or using Git? Or should that
>   go to support?
> - I want to include screenshots in the tutorial. In the past I've hosted
>   blog graphics under people.torproject.org/~dcf/, but I've been told
>   it's better, for the blog, to host them at extra.torproject.org. What
>   is the process for getting files placed on extra.torproject.org?
> 
> ----
> 

It looks great! Do you want help/comments/editions to the blogpost
before posting it?  If you do then I can move your blogpost to a web
document so we can help with edition. After that we can create a user
for you in the blog (if you don't have one already) so you can directly
post it.

> # How to contribute to the Tor metrics timeline
> 
> The [metrics timeline](https://gitlab.torproject.org/tpo/metrics/timeline)
> is a database of news and events that may affect
> [Tor Metrics](https://metrics.torproject.org/) graphs. This post is
> about how you can contribute to the timeline and help keep it up to
> date.
> 
> A timeline of events helps in interpreting graphs. For example, you may
> look at a graph and ask, "Why did the number of Tor users in Sri Lanka
> increase for a week in 2018?"
> 
> [<graph>](https://metrics.torproject.org/userstats-relay-country.html?start=2018-02-01&end=2018-04-15&country=lk&events=off)
> 
> Checking the timeline, we find that at that time in Sri Lanka there was
> a block of Facebook and other services. A likely explanation for the
> increase of users is that people were using Tor to access the blocked
> services.
> 
> |start date|end date|places|protocols|description|links|?  |
> |----------|--------|------|---------|-----------|-----|---|
> |2018-03-07|2018-03-15|lk||Sri Lanka blocks Facebook, Instagram, WhatsApp, and Viber.|[relay graph](https://metrics.torproject.org/userstats-relay-country.html?start=2018-01-01&end=2018-04-01&country=lk) [bridge graph](https://metrics.torproject.org/userstats-bridge-country.html?start=2018-01-01&end=2018-04-01&country=lk) [article](https://www.reuters.com/article/us-sri-lanka-clashes-socialmedia/sri-lanka-lifts-ban-on-facebook-imposed-after-spasm-of-communal-violence-idUSKCN1GR31R)||
> 
> Or you may look at the graph of relays' advertised bandwidth and ask,
> "What accounts for the bump in August 2018?"
> 
> [<graph>](https://metrics.torproject.org/bandwidth.html?start=2019-07-01&end=2019-09-01)
> 
> The timeline has an explanation: it was the result of a temporary
> scientific experiment to test the accuracy of relays' bandwidth reports.
> 
> |start date|end date|places|protocols|description|links|?  |
> |----------|--------|------|---------|-----------|-----|---|
> |2019-08-06|2019-08-09 01:00:00|||Experiment to test the accuracy of relays' advertised bandwidth estimation.|[description of experiment](https://lists.torproject.org/pipermail/tor-relays/2019-July/017535.html) [post announcing start](https://lists.torproject.org/pipermail/tor-relays/2019-August/017599.html) [post announcing end](https://lists.torproject.org/pipermail/tor-relays/2019-August/017617.html) [advertised bandwidth graph](https://metrics.torproject.org/bandwidth.html?start=2019-07-01&end=2019-09-01) [relay flags graph](https://metrics.torproject.org/bandwidth-flags.html?start=2019-07-01&end=2019-09-01)||
> 
> The metrics timeline is useful but incomplete—for example, it tends to
> only include events that make international news. Some past events have
> a start date but are missing an end date. And some events mark unusual
> graph features, but do not have an explanation. You can help the Tor
> Project and people trying to understand use of the Tor network by
> contributing your knowledge to the metrics timeline.
> 
> ## Data format
> 
> The timeline is a
> [text file](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
> in the Tor Project's GitLab.
> Entries are stored in a table under the `## Timeline` heading. The table
> has seven columns:
> 
> ```
> |start date|end date|places|protocols|description|links|?  |
> |----------|--------|------|---------|-----------|-----|---|
> ```
> 
> * **start date**: The date, in the format `2020-12-31`, when the event
>   began (for long-term events) or occurred (for instantaneous events).
> * **end date**: The date when a long-term event ended. This can be blank
>   for instantaneous events, or the special value `ongoing` for an event
>   that has started but not ended yet.
> * **places**: A list of
>   [country codes](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes),
>   separated by spaces. This field may be blank for events that are not
>   limited to a specific geographic region.
> * **protocols**: Some events only affect one or a few of the many
>   protocols used by Tor. For example, this field might contain `obfs4`,
>   `meek`, or `snowflake` if the event affects only one
>   [pluggable transport](https://tb-manual.torproject.org/circumvention/);
>   `bridge` if [bridges](https://tb-manual.torproject.org/bridges/) but
>   not relays are affected; or `onion` if the event involves
>   [onion services](https://tb-manual.torproject.org/onion-services/).
>   Leave the field blank if the event is not specific to a protocol.
> * **description**: A freeform text description of the event.
> * **links**: A list of links to references or other evidence, in
>   [Markdown](https://en.wikipedia.org/wiki/Markdown) format:
>   `[link label](https://example.com)`.
> * **?**: This field indicates whether the event is adequately explained.
>   An `X` in the **?** field means that there is an unusual feature on
>   the graph, but we do not know what caused it. The field is blank when
>   a likely cause is known.
> 
> Here are two examples. The first one had to do with Iran (country code
> `ir`) and is considered adequately explained, with links to two reports.
> The second one affected only the meek pluggable transport in Brazil
> (country code `br`). Its cause is unknown, so it only has a link to a
> graph, and an `X` in the **?** field.
> 
> ```
> |2019-11-16|2019-11-23|ir||Internet blackout in Iran.|[report](https://ooni.org/post/2019-iran-internet-blackout/) [NTC thread](https://ntc.party/t/a-new-kind-of-censoship-in-iran/237)||
> |2017-06-07|2017-12-14|br|meek|Sustained increase of meek users in Brazil, similar to the one that took place between 2016-07-21 and 2017-03-03.|[graph](https://metrics.torproject.org/userstats-bridge-combined.html?start=2016-06-01&end=2018-01-15&country=br)|X|
> ```
> 
> Here are some specific ways you can help:
> * Find an event with `ongoing` in the **end date** field, and see if it
>   really is still ongoing. If it is not, fill in the end date.
> * Think of Tor-related or Internet-related events that have happened in
>   the country you live in, and make sure there is an entry for each of
>   them.
> * Find an event with `X` in the **?** field and search for references or
>   online discussion that may explain it.
> * Search the graphs for unusual features and add entries for them with
>   `X` in the **?** field.
> 
> ## How to contribute
> 
> To add an entry to the metrics timeline, or edit an existing entry, you
> will have to create a Tor GitLab account, edit the file, and make a
> [merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-by-adding-editing-and-uploading-a-file).
> 
> Merge requests are the most convenient way for us to accept changes, but
> if you prefer not to create an account, or if you have trouble with the
> merge request, we still want you to be able to contribute. Contact the
> [metrics team](https://gitlab.torproject.org/tpo/metrics/team) and we
> will try to help.
> 
> 1. Create a GitLab account at https://gitlab.onionize.space/. Where it
>    says "Please explain why you want to collaborate with the Tor
>    community," you can enter "I want to help with the metrics timeline."
>    Then wait until the new account is approved.
> 2. Log in with your account and go to
>    [README.md](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
>    file in the metrics timeline repository.
> 3. Click the blue "Edit" button. The first time you do this, you will
>    see a message:
>    > You're not allowed to edit files in this project directly. Please
>    > fork this project, make your changes there, and submit a merge
>    > request.
>    Click the "Fork" button.
> 4. Now you may edit the text file. You may want to change the "No wrap"
>    setting to "Soft wrap" to make it easier to read. Scroll down, below
>    the the `## Timeline` heading, and make your change. In the "Commit
>    message" box, enter a one-sentence summary of the change, like "March
>    2021 outage in <country>." Click the green "Commit changes" button.
> 5. At the "New Merge Request" page, leave the default options and click
>    the green "Submit merge request" button.
> 
> Now the merge request is created. You will get a notification by email
> when it is approved, or if the maintainers have questions.
> 
> ## Step-by-step example
> 
> Let's go step by step through the process of finding something to
> improve, making the change, and starting a merge request. We will look
> for an ongoing event without an end date and find out when it actually
> ended.
> 
> First we go to the file
> [README.md](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
> and do a Ctrl+F search for "ongoing". This finds a shutdown event in
> Ethiopia in mid-2020, which was ongoing at the time the event was added:
> 
> |2020-06-30 05:00:00|ongoing|et||Internet shutdown in Ethiopia.|[article](https://edition.cnn.com/2020/06/30/africa/ethiopia-singer-killing-sparks-protest-intl/) [IODA](https://ioda.caida.org/ioda/dashboard#view=inspect&entity=country/ET&lastView=overview&from=1593192460&until=1593797260) [relay users graph](https://metrics.torproject.org/userstats-relay-country.html?start=2020-06-01&end=2020-07-31&country=et&events=off)||
> 
> Looking at the
> [graph of directly connecting users](https://metrics.torproject.org/userstats-relay-country.html?start=2020-06-01&end=2020-07-31&country=et&events=off)
> from that time, the effect of the shutdown on June 30 is obvious,
> but it looks like the number of users recovers a few weeks later:
> 
> [<graph>](https://metrics.torproject.org/userstats-relay-country.html?start=2020-06-01&end=2020-07-31&country=et&events=off)
> 
> Then we do a web search for terms like "Ethiopia Internet shutdown
> 2020". We find
> [an article](https://qz.com/africa/1884387/ethiopia-internet-is-back-on-but-oromo-tensions-remain/)
> saying that Internet access was partially restored on July 15 and the
> shutdown ended on July 23, which is consistent with the Tor Metrics
> graph. We will make three changes to the entry:
> 
> 1. Change the **end date** field to `2020-07-23`.
> 2. Note the 2020-07-15 partial restoration of access in the
>    **description** field.
> 3. Add a link to the article to the **links** field.
> 
> Still at the
> [README.md](https://gitlab.torproject.org/tpo/metrics/timeline/-/blob/master/README.md)
> page, we click the blue "Edit" button, then the green "Fork" button.
> 
> <screenshot>
> 
> We scroll down to find the entry we are interested in:
> 
> <screenshot>
> 
> And then we make the changes:
> 
> 1. Set **end date** to `2020-07-23`.
> 2. Add to **description** `Restrictions were partially lifted
>    2020-07-15.`.
> 3. Add to **links**
>    `[article](https://qz.com/africa/1884387/ethiopia-internet-is-back-on-but-oromo-tensions-remain/)`.
> 
> <screenshot>
> 
> In the "Commit message" box, we enter "June 2020 shutdown in Ethiopia
> ended in July," the click the green "Commit changes" button.
> 
> <screenshot>
> 
> We arrive at a page titled "New Merge Request." We leave all the options
> unchanged and click the green "Submit merge request" button.
> 
> <screenshot>
> 
> Now the merge request is created and you are done. Just wait for the
> maintainer to merge the change or leave a comment. You will get an email
> notification when something in the merge request changes.
> 
> You can see the merge request that was created and merged for this
> example at
> [tpo/metrics/timeline!2](https://gitlab.torproject.org/tpo/metrics/timeline/-/merge_requests/2).
> _______________________________________________
> metrics-team mailing list
> metrics-team at lists.torproject.org
> https://lists.torproject.org/cgi-bin/mailman/listinfo/metrics-team
> 