docs: prepare README and CONTRIBUTING before publishing (#131)

CONTRIBUTING.md

@@ -27,8 +27,8 @@ We have CI jobs running for every PR to test and lint the repository. You can in
 that these check pass even *before pushing your changes* to GitHub. To use this, the following steps are required:
 
 1. Install [Rust](https://www.rust-lang.org/tools/install).
-1. Install [cargo-deny](https://embarkstudios.github.io/cargo-deny/cli/index.html).
 1. [Install pre-commit](https://pre-commit.com/#install) using `pip` or your OS's package manager.
+1. Install required cargo tools: `cargo install cargo-sort cargo-deny``
 1. Run `pre-commit install` in the repository.
 
 After this setup, the code will be checked, reformatted, and tested whenever you create a Git commit.
@@ -45,12 +45,14 @@ To analyze test coverage, we use [Tarpaulin](https://crates.io/crates/cargo-tarp
 
 ```sh
 cargo install cargo-tarpaulin
-cargo tarpaulin --workspace --all-targets --doc --out html
+cargo tarpaulin --workspace --skip-clean --lib --bins --examples --tests --doc --out html
 ```
 
 This creates a file `tarpaulin-report.html`, which shows you coverage statistics as well as which individual lines are or aren't covered by tests.
 Other valid output formats are `json`, `stdout`, `xml`, and `lcov`.
 
+The exact command we use in our CI pipeline is visible in [.github/workflows/rust.yml](.github/workflows/rust.yml).
+
 ## Integration tests
 
 Most integration tests are disabled by default because they depend on certain running SCION applications.
@@ -65,7 +67,7 @@ can run integration tests like this:
 SCION_DAEMON_ADDRESS="http://192.168.0.42:12345" cargo test -- --ignored
 ```
 
-For the integration tests, we use the
+The following section describes how to set up the SCION components used for integration tests locally.
 
 ### Local SCION topology with multipass
 

README.md

@@ -1,14 +1,47 @@
 # SCION in Rust
 
 This library provides an end-host networking stack for SCION and can be used in Rust applications to communicate over a
-SCION network.
+SCION network. The library is fully compatible with the [reference implementation](https://github.com/scionproto/scion)
+written in Go. In terms of functionality, it is a combination of the Go
+[snet](https://pkg.go.dev/github.com/scionproto/scion/pkg/snet) and
+[pan](https://pkg.go.dev/github.com/netsec-ethz/scion-apps/pkg/pan) libraries. See the [section about the repository
+structure](#repository-structure-and-crates) for further details.
 
-If you would like to contribute (which we highly appreciate), please familiarize yourself with our [contributing
-workflow](./CONTRIBUTING.md).
+In the future, it will be extended to offer QUIC-over-SCION sockets similar to the
+[shttp3 library](https://pkg.go.dev/github.com/netsec-ethz/scion-apps/pkg/shttp3).
 
-## Prerequisites
+If you observe a bug or want to request a feature, please search for an existing [issue](https://github.com/MystenLabs/scion-rs/issues)
+on this topic and, if none exists, create a new one. If you would like to contribute code directly (which we highly
+appreciate), please familiarize yourself with our [contributing workflow](./CONTRIBUTING.md).
 
-### Ubuntu
+## How to use this library
+
+As our crates are not yet published to crates.io, you need to include them as a Git dependency in your `Cargo.toml`
+file. Most likely, you will need the `scion` crate as explained [below](#repository-structure-and-crates), but you can
+also use the `scion_proto` crate if you only need the main types and no asynchronous communication.
+
+In the `[Dependencies]` section of your `Cargo.toml` file, add the following:
+
+```toml
+scion = { git = "ssh://git@github.com/MystenLabs/scion-rs" }
+```
+
+Optionally, you can specify a tag or branch, for example:
+
+```toml
+scion = { git = "ssh://git@github.com/MystenLabs/scion-rs", tag = "v0.1.0" }
+```
+
+Further details are provided in
+[this documentation](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories).
+
+### Prerequisites
+
+Due to its use of gRPC for communicating with external SCION components, this library requires protobuf to be installed.
+
+For Ubuntu and MacOS, you can use the following snippets to install all prerequisites.
+
+#### Ubuntu
 
 ```sh
 # Install C/C++ compilers, protobuf, SQLite3, clang
@@ -17,7 +50,7 @@ sudo apt install -y build-essential protobuf-compiler libsqlite3-dev llvm-dev li
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-### Mac
+#### MacOS
 
 ```sh
 # Install Homebrew
@@ -28,25 +61,45 @@ brew install protobuf
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-## Build and test
+### Logging
+
+We use [tracing](https://github.com/tokio-rs/tracing) to log messages during program execution. By instantiating an
+appropriate [subscriber](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/) in your application, you can
+control which messages are logged and how.
+
+## Repository structure and crates
+
+This codebase consists of three different crates in the [`crates`](./crates) subdirectory:
+
+1. [`scion-proto`](./crates/scion-proto/) contains the main types and conversions to represent SCION packets, addresses,
+   paths, etc.
+1. [`scion-grpc`](./crates/scion-grpc/) contains the automatically generated gRPC code to interact with external SCION
+   components like the SCION daemon.
+1. [`scion`](./crates/scion/) contains all asynchronous code for sockets, to send and receive packets, to fetch and
+   cache paths, etc.
+
+If you build an application that uses SCION, you will most likely need the `scion` crate, which includes the others as
+dependencies.
 
-- Build the project: `cargo build`
-- Run the tests: `cargo test`
+All crates contain extensive documentation. Please see the following section on how to access it.
 
-## Logging
+## Documentation
 
-We use [tracing](https://github.com/tokio-rs/tracing) to log messages during program execution. By default, only
-warnings and errors are printed. You can control the level of messages to be printed through the environment variable
-`RUST_LOG`. For example, to print info messages in addition, you can execute the following:
+Most of our code has associated documentation. You can build and access this documentation locally by cloning the
+repository and using `cargo-doc`:
 
 ```sh
-export RUST_LOG=info
+git clone https://github.com/MystenLabs/scion-rs
+cd scion-rs
+cargo doc --workspace --open
 ```
 
 ## Specification and standards
 
 We use the protobuf definitions and other specification from [scionproto/scion](https://github.com/scionproto/scion) and
-the [SCION documentation](https://docs.scion.org).
+the [SCION documentation](https://docs.scion.org) as well as the SCION-related Internet drafts, see
+[draft-dekater-panrg-scion-overview](https://datatracker.ietf.org/doc/draft-dekater-panrg-scion-overview/) and
+references therein.
 
 ## License