Skip to content

Latest commit

 

History

History
112 lines (78 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

112 lines (78 loc) · 5.24 KB
Raw

How to Contribute

GitHub flow

We generally follow the GitHub flow in our project. In a nutshell, this requires the following steps to contribute:

  1. Fork the repository (only required if you don't have write access to the repository).
  2. Create a feature branch.
  3. Make changes and create a commit; note that we enforce a particular style for commit messages, see below.
  4. Push your changes to GitHub and create a pull request (PR).
  5. Wait for maintainers to review your changes and, if necessary, revise your PR.

Commit messages

To ensure a consistent Git history (from which we can later easily generate changelogs automatically), we enforce that all commit messages and PR titles comply with the conventional-commit format. For examples, please take a look at our commit history.

Pre-commit hooks

We have CI jobs running for every PR to test and lint the repository. You can install Git pre-commit hooks to ensure that these check pass even before pushing your changes to GitHub. To use this, the following steps are required:

  1. Install Rust.
  2. Install pre-commit using pip or your OS's package manager.
  3. Install required cargo tools: `cargo install cargo-sort cargo-deny``
  4. Run pre-commit install in the repository.

After this setup, the code will be checked, reformatted, and tested whenever you create a Git commit.

You can also use a custom pre-commit configuration:

  1. Create a file .custom-pre-commit-config.yaml (this is set to be ignored by Git).
  2. Run pre-commit install -c .custom-pre-commit-config.yaml.

Test coverage

We would like to cover as much code as possible with tests. Ideally you would add unit tests for all code you contribute. To analyze test coverage, we use Tarpaulin. You can install and run the tool as follows:

cargo install cargo-tarpaulin
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.

Integration tests

Most integration tests are disabled by default because they depend on certain running SCION applications. You can run the integration tests by executing cargo test -- --ignored or the full test suite (unit and integration tests) through cargo test -- --include-ignored.

Some integration tests allow you to control addresses of SCION components and other data through environment variables. For example, if your SCION Daemon is accessible at 192.168.0.42:12345 instead of the default localhost:30255, you can run integration tests like this:

SCION_DAEMON_ADDRESS="http://192.168.0.42:12345" cargo test -- --ignored

The following section describes how to set up the SCION components used for integration tests locally.

Local SCION topology with multipass

If you are on a supported Linux distribution you can set up a local SCION development environment directly on your machine and run a local SCION topology.

If you run a different operating system, you can conveniently manage Ubuntu VMs with Multipass. The following command can be used to launch a new VM, install prerequisites inside the VM, install the latest version of SCION, and run a local topology with services accessible from the host machine:

multipass launch --name scion --disk 10G --memory 4G --cpus 2 --timeout 600 \
    --cloud-init multipass/cloud-config.yaml

This will take several minutes as it builds SCION from source (hence the increased timeout).

After the launch, you can check that the network started successfully and that you see paths:

multipass shell scion

sudo systemctl status scion-network.service

cd /etc/scion-rs-integration/scion/
bin/scion showpaths --sciond $(./scion.sh sciond-addr 111) 1-ff00:0:112

Now you can access SCION services from the host system and forward the dispatcher UNIX socket to run integration tests. For convenience, you can use the test_setup.sh script:

chmod 0600 ./multipass/test_id_ed25519
. ./multipass/test_setup.sh
cargo test -- --ignored

Signed commits

We appreciate it if you configure Git to sign your commits.