# Contributing

Corrections, new measurements and independent re-analyses are welcome,
including ones that disagree with the results. Every figure on pingstats,
fe-map and iss is rebuilt from this repository, so a change accepted here
changes the published numbers. The Shape of Distance is included as published.

Issues and pull requests: https://github.com/aetherbird/cable-latency-survey
(a mirror of https://git.aethercosmology.com/toby/cable-latency-survey with the same history).

## Report a problem

Open an issue that names the page, the pair or value, what you believe is
wrong, and the evidence (a source, a log, a measurement ID). Typical cases: a
server or probe listed in the wrong city, a flight time that does not match its
track log, a cable length that differs from its published figure, or a step in
a method that you think biases the result.

## Add measurements

Measurements that anyone can re-fetch are the most useful. Include the raw
output, not only a summary.

| Kind | What to send |
|---|---|
| Ping or traceroute | A RIPE Atlas or Globalping measurement ID; or the raw output of `ping -c 20` and `mtr -rwc 20` with the UTC time, the target, and the source city (a public anchor, a hosted server, or your city to within 25 km). |
| Flight | Flight number and date for both directions, the track log URL (FlightAware or another ADS-B record), and the aircraft type. |
| Rail or road | The route and its published length, with the source. |
| Satellite pass | SatNOGS observation IDs, or raw recordings with station location and UTC timestamps. |

Routes in the southern hemisphere are the most informative: South America to
Africa and Australia, Africa to Australia, and New Zealand to anywhere.

Do not post your home IP address or street address. A city is enough.

## Change the analysis

Fork the repository, make the change, run the build of the page it affects and
the browser checks, and open a pull request that states how the published
numbers change.

| Site | Source | Build |
|---|---|---|
| pingstats.aethercosmology.com | `src/` | `cd src && python3 build.py` |
| fe-map.aethercosmology.com | `femap/` | `cd femap && python3 build.py` (about 10 minutes) |
| iss.aethercosmology.com | `satellites/` | `cd satellites && python3 build.py` |
| distance.aethercosmology.com | `src/handoff/The_Shape_of_Distance_PRESENTATION.html` | single published file |

Browser checks: `cd tests && npm install && CH=/path/to/chromium ./run.sh`.

## Rules applied to every contribution

- Each value traces to a public source, a measurement ID, or a raw log in this
  repository.
- A measurement is not removed for disagreeing with a model. Cleaning rules,
  such as the one for mislocated servers, are stated in each page's method
  section and apply to every measurement alike.
- Code is contributed under the MIT licence (`LICENSE`); data under CC BY 4.0
  (`LICENSE-DATA.md`).