improve contribution guide

CONTRIBUTING.md

@@ -1,3 +1,4 @@
 # Contribution Guide
 
-The Contribution Guide for the SCION project can be found [here](doc/Contribute.rst).
+The Contribution Guide for the SCION project can be found
+[here](https://anapaya-scion.readthedocs-hosted.com/en/latest/contribute.html).

README.md

@@ -4,113 +4,28 @@
 [![ReadTheDocs](https://img.shields.io/badge/doc-reference-blue?version=latest&style=flat&label=docs&logo=read-the-docs&logoColor=white)](https://anapaya-scion.readthedocs-hosted.com/en/latest)
 [![Build Status](https://badge.buildkite.com/e7ca347d947c23883ad7c3a4d091c2df5ae7feb52b238d29a1.svg?branch=master)](https://buildkite.com/scionproto/scion)
 [![Go Report Card](https://goreportcard.com/badge/github.com/scionproto/scion)](https://goreportcard.com/report/github.com/scionproto/scion)
-[![GitHub issues](https://img.shields.io/github/issues/scionproto/scion/help%20wanted.svg?label=help%20wanted&color=blue)](https://github.com/scionproto/scion/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
+[![GitHub issues](https://img.shields.io/github/issues/scionproto/scion/help%20wanted.svg?label=help%20wanted&color=purple)](https://github.com/scionproto/scion/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
+[![GitHub issues](https://img.shields.io/github/issues/scionproto/scion/good%20first%20issue.svg?label=good%20first%20issue&color=purple)](https://github.com/scionproto/scion/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
 [![Release](https://img.shields.io/github/release-pre/scionproto/scion.svg)](https://github.com/scionproto/scion/releases)
-[![license](https://img.shields.io/github/license/scionproto/scion.svg?maxAge=2592000)](https://github.com/scionproto/scion/blob/master/LICENSE)
+[![License](https://img.shields.io/github/license/scionproto/scion.svg?maxAge=2592000)](https://github.com/scionproto/scion/blob/master/LICENSE)
 
-An implementation of [SCION](http://www.scion-architecture.net), a future
-Internet architecture.
+Welcome to the open-source implementation of [SCION](http://www.scion-architecture.net) (Scalability, Control and Isolation On next-generation Networks), a future Internet architecture. SCION is the first clean-slate Internet architecture designed to provide route control, failure isolation, and explicit trust information for end-to-end communication.
+To find out more about the project, please visit our
+[documentation site](https://anapaya-scion.readthedocs-hosted.com/en/latest/).
 
-* [docker/](/docker): support files to run SCION inside of Docker
-  containers.
-* [go/](/go): parts of the implementation that are written in
-  [Go](http://golang.org).
-    * [border_router](/go/border): Border Router
-    * [certificate_server](/go/cert_srv): Certificate Server
-    * [scion_ip_gateway](/go/sig): SCION IP Gateway
-    * [lib](/go/lib): shared SCION Go libraries
-* [python/](/python): the parts of the infrastructure
-  implemented in Python.
-    * [lib/](/python/lib): shared SCION Python libraries
-    * [topology](/python/topology): generator for generating a local topology,
-        including all the necessary configuration, key, and certificate files
-* [proto/](/proto): the protocol definitions for use with [Cap’n
-  Proto](https://capnproto.org/).
-* [supervisor/](/supervisor): the configuration for
-  [supervisord](http://supervisord.org/)
-* [tools/](/tools): assorted support tools
-* [topology/](/topology): various topology definitions and configurations
+### Connecting to the SCION Test Network
 
-Necessary steps in order to run SCION:
+Join [SCIONLab](https://www.scionlab.org) if you're interested in playing with SCION in an operational global test deployment of SCION. As part of the SCIONLab project, we support [pre-built binaries as Debian packages](https://docs.scionlab.org/content/install/).
 
-1. Make sure that you are using a clean and recently updated **Ubuntu 16.04**.
-   This environment assumes you're running as a non-root user with sudo access.
+### Building
 
-1. Install [Bazel](https://bazel.build) version 1.2.0:
+To find out how to work with SCION, please visit our [documentation site](https://anapaya-scion.readthedocs-hosted.com/en/latest/contribute.html#setting-up-the-development-environment) for instructions on how to install build dependencies, build and run SCION.
 
-   ```bash
-   sudo apt-get install g++ unzip zip
-   wget https://github.com/bazelbuild/bazel/releases/download/1.2.0/bazel-1.2.0-installer-linux-x86_64.sh
-   bash ./bazel-1.2.0-installer-linux-x86_64.sh --user
-   rm ./bazel-1.2.0-installer-linux-x86_64.sh
-   ```
+## Contributing
 
-1. Check out scion into the appropriate directory inside your workspace:
+Interested in contribution to the SCION project? Please visit us at [contribute.rst](https://anapaya-scion.readthedocs-hosted.com/en/latest/contribute.html) for more information about how you can do so.
 
-   ```bash
-   cd "<workspace>"
-   git clone https://github.com/scionproto/scion
-   cd scion
-   ```
+## License
 
-1. Install required packages with dependencies:
+[![License](https://img.shields.io/github/license/scionproto/scion.svg?maxAge=2592000)](https://github.com/scionproto/scion/blob/master/LICENSE)
 
-   ```bash
-   ./env/deps
-   ```
-
-1. Install `docker` and `docker-compose`. Please follow the instructions for
-   [docker-ce](https://docs.docker.com/install/linux/docker-ce/ubuntu/) and
-   [docker-compose](https://docs.docker.com/compose/install/). Add your user to the docker group:
-   `sudo usermod -a -G docker $LOGNAME`. Log out and log back in so that your group membership is
-   re-evaluated.
-
-1. Create the topology and configuration files (according to
-   `topology/Default.topo`):
-
-   `./scion.sh topology`
-
-   The resulting directory structure will be created:
-
-   ```bash
-   ./gen/ISD{X}/AS{Y}/
-       {elem}{X}-{Y}-{Z}/
-           as.yml
-           path_policy.yml
-           supervisord.conf
-           topology.yml
-           certs/
-               ISD{X}-AS{Y}-V0.crt
-               ISD{X}-V0.trc
-           keys/
-               as-sig.key
-   ```
-
-   The default topology looks like [this](doc/fig/default_topo.png).
-
-1. Run the infrastructure:
-
-    `./scion.sh run`
-
-1. Stop the infrastructure:
-
-    `./scion.sh stop`
-
-Notes about `topology/Default.topo`:
-
-* `defaults.subnet` (optional): override the default subnet of `127.0.0.0/8`.
-
-* `core` (optional): specify if this is a core AS or not (defaults to 'false').
-
-* `control_servers` (optional):
-  number of such servers in a specific AS (override the default value 1).
-
-* `links`: keys are `ISD_ID-AS_ID` (format also used for the keys of the JSON
-  file itself) and values can either be `PARENT`, `CHILD`, `PEER`, or
-  `CORE`.
-
-## Tests
-
-In order to run the unit tests:
-
-  `./scion.sh test`

doc/build/setup.rst

@@ -0,0 +1,77 @@
+.. _setting-up-the-development-environment:
+
+Setting up the development environment
+======================================
+
+#. Make sure that you are using a clean and recently updated **Ubuntu 18.04**.
+   This environment assumes you're running as a non-root user with ``sudo`` access.
+#. We use `Bazel <https://bazel.build>`__ for both building and testing. To set up the
+   development environment, please install Bazel version 1.2.0:
+
+   .. code-block:: bash
+
+      sudo apt-get install g++ unzip zip
+      wget https://github.com/bazelbuild/bazel/releases/download/1.2.0/bazel-1.2.0-installer-linux-x86_64.sh
+      bash ./bazel-1.2.0-installer-linux-x86_64.sh --user
+      rm ./bazel-1.2.0-installer-linux-x86_64.sh
+
+#. Next, clone the SCION repository into the appropriate directory inside your workspace. In the commands below,
+   replace ``${WORKSPACE}`` with the directory in which you want to set up the project:
+
+   .. code-block:: bash
+
+      cd ${WORKSPACE}
+      git clone https://github.com/scionproto/scion
+      cd scion
+
+#. For this step, make sure you are in the ``scion`` repository root. To install the required dependencies, run:
+
+   .. code-block:: bash
+
+      ./env/deps
+
+#. (Optional) If you want to run applications via docker, install ``docker`` and ``docker-compose``.
+   Please follow the instructions for `docker-ce <https://docs.docker.com/install/linux/docker-ce/ubuntu/>` and
+   `docker-compose <https://docs.docker.com/compose/install/>`. Then, add your user to the ``docker`` group:
+   ``sudo usermod -a -G docker ${LOGNAME}``, where ``${LOGNAME}`` is replaced with your user name. Log out
+   and log back in so that your membership of the ``docker`` group is seen by the shell session.
+#. SCION networks are composed of many different applications. To simplify testing, we provide a
+   tool that generates test topologies. To generate the files required by the default topology (see
+   ``doc/fig/default_topo.png`` for a diagram of this topology), run:
+
+   .. code-block:: bash
+
+      ./scion.sh topology
+
+   The above command creates the ``gen`` directory, which contains configuration files and cryptographic
+   material for multiple SCION ASes and ISDs.
+#. To start the infrastructure we just generated, run:
+
+   .. code-block:: bash
+
+      ./scion.sh run
+
+#. To verify that your topology is running correctly, you can run an end to end reachability test using:
+
+   .. code-block:: bash
+
+      ./bin/end2end_integration
+
+#. To stop the infrastructure, run:
+
+   .. code-block:: bash
+
+      ./scion.sh stop
+
+#. Finally, check that unit tests run correctly:
+
+    .. code-block:: bash
+
+       ./scion.sh test
+
+#. (Optional) If you already have some code you wish to contribute upstream, you can also run the
+   linters locally with:
+
+   .. code-block:: bash
+
+      ./scion.sh lint