From 2b80ffae1127ee27e1a81820798b41fad0c6b282 Mon Sep 17 00:00:00 2001 From: "Density 21.5" Date: Wed, 7 Jan 2026 14:46:25 +0100 Subject: [PATCH 1/5] change README, ROADMAP to point to discourse forum. add other mds --- CONTRIBUTING.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 ++- RELEASING.md | 65 +++++++++++++++++++ ROADMAP.md | 84 +----------------------- TESTING.md | 53 +++++++++++++++ 5 files changed, 294 insertions(+), 84 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 RELEASING.md create mode 100644 TESTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..db0932dd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,168 @@ +# Contributing to Rotonda + +Hi! Thank you for wanting to contribute to Rotonda. + +This document offers guidelines on how best to contribute. Following the +guidelines here give your contributions the best chance at getting merged. + +## Code of Conduct + +This project and everyone participating in it is governed by the [NLnet Labs +Code of Conduct]. By participating, you are expected to uphold this code. + +## A note on Generative AI + +We do not accept any content -- code, documentation or otherwise -- generated +by large language models or other generative AI. + +## Discussion + +### Asking questions + +The best place to ask questions is on [Discourse]. Please look through +existing posts before creating a new thread. + +### Reporting security vulnerabilities + +See [SECURITY.md]. + +### Reporting other bugs + +If you find something that is clearly a bug, you can submit it directly to the +issue tracker. Please look though existing issues before creating a new issue. +You should also check whether your issue has already been addressed on the +`main` branch. + +Try to include as much as possible of the following information: + + - Version/branch/commit of Rotonda you are using + - Your system (OS, architecture) + - Any stack traces or logging messages + - A reproducer that shows the issue + +### Suggesting enhancements + +If you have ideas for improving Rotonda, you can start a discussion about it +on [Discourse]. Please look through other posts to see whether your idea has +been discussed before. + +Be sure to include clear use-cases and motivation for your idea. + +## Contribution + +### License and copyright + +When contributing with code or other content, you agree to put your changes +and new code under the same license Rotonda and its associated libraries is +already using. When changing existing source code, do not alter the copyright +of the original file(s). The copyright will still be owned by the original +creator(s) or those who have been assigned copyright by the original +author(s). + +By submitting a patch to Rotonda, you are assumed to have the right to +the code and to be allowed by your employer or whatever to hand over that +patch/code to us. We will credit you for your changes as far as possible, to +give credit but also to keep a trace back to who made what changes. + +### Contributing documentation + +Writing documentation is very hard, but _very_ appreciated. Improving +the documentation could mean anything from adding new chapters to +fixing a typo. The documentation of Rotonda has a repository of its +[own](https://github.com/nlnetLabs/rotonda-doc). + + - Go to the `/manual/docs/` folder of this repository. + +The documentation in the `/manual/docs/` folder is written in +[reStructuredText] and hosted [ReadTheDocs] via [Sphinx]. If you have the [uv] +tool installed, you can easily build the documentation locally with + +``` +make html +``` + +You can then serve those files however you want, for example using + +``` +python -m http.server +``` + +You can submit your changes in a pull request. A preview version of the updated +documentation will be built automatically for your PR. You can view it by +clicking on the ReadTheDocs action on the PR page or by visiting + +``` +https://rotonda--XXX.org.readthedocs.build/ +``` + +where `XXX` is the number of your PR. + +### Contributing code + +Before you start contributing code, ensure that the issue you are tackling has +been properly discussed either on [Discourse] or the [issue tracker]. Do not +submit pull requests for changes that have not been discussed. + +You can contribute code by opening a pull request. Before you do you +should check that you code passes all tests and adheres to the [style +guide](#style-guide). You do not have to update `Changelog.md`. That will be +updated when a release is tagged. + +You run the code, you'll need to have a working and recent enough Rust +toolchain installed. The [just] tool can also come in handy to run some common +commands on this repository. + +Keep the following in mind while submitting your code: + + - Make sure to link the appropriate issue for your change. If there is none, + make the issue and discuss the change before submitting the PR. + - Make the title and description descriptive. For example, do not make the + title just "Fix #345", but include a description. + - Use descriptive commit messages. + - Your code can only be merged once the CI is green. + - Keep your PRs self-contained and do not include unrelated changes. It's + better to submit many small PRs than one big PR with multiple changes. + +See [TESTING.md] for information on how to test your changes. + +### Style guide + +We follow standard style guides for Rust code. That is, we require that the +code is formatted by `rustfmt` and that it passes the checks of the latest +version of the `clippy` linter. The code should also be free of warnings +generated by `rustc`. + +Rotonda tries to minimize on `unsafe` code. This is not to say that we don't +rely on `unsafe` code, but we are trying to isolate it in separate crates as +much as possible, i.e. the `routedb` crate. If you really must use `unsafe` +code, we require that Valgrind does not raise any issues on test suite. Each +`unsafe` block be accompanied by a `SAFETY` comment and each `unsafe` function +should have a "Safety" section in its documentation. We generally do not rely +on `unsafe` just to achieve better performance. + +## Maintainance + +This section is meant for maintainers of Rotonda, not for all contributors. + +### Dependencies + +Be careful pulling in new dependencies. We should not pull in large +dependencies for small gains. The license should also be compatible with +Rotonda's license. You can use `cargo deny` to check that. + +### Releases + +The steps for releasing a new version of Rotonda are described in RELEASING.md +in the root of this repository. + +[NLnet Labs Code of Conduct]: https://www.nlnetlabs.nl/conduct +[Discourse]: https://community.nlnetlabs.nl/c/rotonda/5 +[issue tracker]: https://github.com/rotonda/NLnetLabs/issues +[reStructuredText]: http://www.sphinx-doc.org/en/stable/rest.html +[ReadTheDocs]: https://readthedocs.org/ +[Sphinx]: http://www.sphinx-doc.org +[uv]: https://docs.astral.sh/uv/ +[just]: https://just.systems/man/en/ +[SemVer]: https://semver.org/ +[SECURITY.md]: ./SECURITY.md +[TESTING.md]: ./TESTING.md diff --git a/README.md b/README.md index 81564b39..0a070827 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,13 @@ install and use Rotonda. > 0.x versions. > > For more information on upcoming features and changes see the -> [ROADMAP](ROADMAP.md) +> [roadmap](https://community.nlnetlabs.nl/t/rotonda-roadmap-for-2026/34/5). + +Go to the [community forum](https://community.nlnetlabs.nl/c/rotonda/5) to +get support from the community, exchange experiences, open issues, and more. + +Rather than opening issues on GitHub we encourage you to open topics on our +forum. ## GOALS diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..bca1ab1f --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,65 @@ +Rotonda RC and Final Release + +For a final release the workflow is the same as for an RC. Just leave out the +`-rcXX` everywhere it is mentioned. + +A. CREATE RELEASE BRANCH + + * create release branch with name release-x.y.0-rcz, e.g. release-0.1.0-rc0. + Note: we start counting at ZERO for the rc, and there's no '.' or '-' in + between rc and the number. + * Update [package] version field in Cargo.toml (e.g. version = "0.1.0-rc0"). + * Finalize Changelog.md: + * Add release date in the form "Released yyyy-mm-dd.". Note the dot at the + end. + * Remove unused sections. + * Review & update dependencies in `Cargo.toml`. + * Run `cargo update` + * If the previous step actually updated any crates, run `cargo check + --all-features --tests --release --examples`. If there are any warnings + and/or errors, fix them and go back to step A.4. + * [library only] Run cargo +nightly test -Z minimal-versions --release + --all-features. If there are any warnings and/or errors, fix them and go + back to step A.4. + * Add and commit changes to this release branch. + * Run `cargo package`. This will try building the crate locally, and will + output warnings and/or errors. If there are any, fix those, and add & + commit these fixes. Run cargo package again to see if they are actually + fixed. + * Push changes to GitHub (e.g. `git push --set-upstream origin release-0.1.i + 0-rc0`). + + +B. CREATE PULL REQUEST + + * Create pull request on GitHub main ← release-x.y.0-rcz and wait for CI + to finish. + * Merge pull request. Add the changes for the release from Changelog.md as + the commit message body (the GitHub web UI lets you do this). + + +C. TAG ON BRANCH MAIN AND RELEASE PACKAGE + + * Check out branch `main` and pull + * Double-check `Cargo.toml` and `Changelog.md`. + * Run `cargo publish` + * Create and push release tag with tag of form vx.y.0-rcz, e.g. `git tag -a + v0.1.0-rc0`. + * Add the changes for the release from Changelog.md as the tag message body + (Same as the merge commit message from the previous PR). + * Push the tag to GitHub (e.g. `git push --tags`). + * [Application Only] Create a release on GitHub. + + +D. CREATE POST RELEASE COMMIT + + * Still in branch `main`. Add new section to `Changelog.md` called + Unreleased new version. + * `Cargo.toml`: Increase version. + * [Application Only] Cargo.lock: Run cargo update -p , + e.g. `cargo update -p rotonda` + + +E. CREATE PACKAGES ON PACKAGES.NLNETLABS.NL + + (not described here) diff --git a/ROADMAP.md b/ROADMAP.md index 87c4c3a1..3f432447 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,86 +2,4 @@ Roadmap ======= -- ✅ work item complete -- 🦀 work item in progress -- 💤 work item not started yet - - -## `Rotonda` - -### 0.3: Collector functionality - -- 💤 Provide passive external data sources to Roto, specifically with Routinator. -- 💤 On-disk storage to prevent growing memory use -- 💤 More ingress connectors (e.g. Kafka, mrt (finalise), rtr) - -### LATER RELEASES - -- 💤 Switch to daemon-base -- 💤 Store other AFI/SAFI types than unicast & multicast -- 💤 CLI for querying RIBs -- 💤 Emit BGP packets as events on OutputStream -- 💤 Egress modified/created BGP packets (on peering sessions) -- 💤 Refactor configuration: dynamic units reconfiguration with RESTCONF/yang+json -- 💤 More egress connectors (e.g. Kafka, Parquet, mrt, (timescale) RDBMS) -- 💤 BMP & BGP proxy -- 💤 BMP out stream -- 💤 Long-term file storage -- 💤 Create experimental global registry -- 💤 Snapshot/restore functionality -- 💤 RIB diff functionality -- 💤 Create experimental distributed Rotondas (Sharding) - - -## `Roto language` - -### NEXT RELEASE 0.4 - -- 🦀 Create dev documentation -- 🦀 Create reference-level documentation -- 💤 accomodate querying RIBs as external data source -- 💤 Schemas and dynamic types in Roto functions -- 💤 Global variables -- 💤 Create namespaces / modules system - -### LATER RELEASES - -- 💤 implement more passive external data sources -- 💤 create user-configurable graph DSL for units -- 💤 create user-configurable query DSL - - -## `Routecore` - -### NEXT RELEASE 0.6 - -- 💤 Optimizations - -### LATER RELEASES - -- 💤 BGPsec parser -- 💤 More AFI/SAFI types -- 💤 Move BMP FSM from Rotonda to Routecore -- 💤 Refactor BGP FSM with BoQ in mind -- 💤 Type-aware wire format path attributes - - -## `Rotonda-store` - -### NEXT RELEASE 0.5 - -- 🦀 On-disk storage integration -- 🦀 Optimizations: better hashing, cache padding, etc. - -### LATER RELEASES - -- 💤 Query Plans -- 💤 Indexing (dynamic and static) - -## `Rotoro` - -### MVP - -- 🦀 Design wire protocol and select a layout (AVRO?) -- 💤 Create experimental de/serialization -- 💤 Experimental integration in `rotonda` +The roadmap can be found [here](https://community.nlnetlabs.nl/t/rotonda-roadmap-for-2026/34/5). diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 00000000..d25912bf --- /dev/null +++ b/TESTING.md @@ -0,0 +1,53 @@ +# Testing + +The tests of Rotonda live in a few places: + + - the `/tests` + - unit tests in the source code + - doctests in the source code + +Running these tests is done with a single command: +``` +cargo test --all-features --release +``` + +Use with `cargo nextest` is probably possible, but, well, untested. + +## Snapshot testing + +Some of the tests use snapshot testing using [insta]. You can run +them with the regular Rust test runner, but to change them, you might want to +install `cargo-insta` with `cargo install cargo-insta`. See the [insta] website for more information. + +## Valgrind + +If you want to submit `unsafe` code to Rotonda, we require that the entire +test suite is run under [Valgrind]. To do that locally, you'll need to install +Valgrind and `cargo-valgrind`. + +If you have [just] installed, you can run the test suite under valgrind with + +``` +just valgrind +``` + +But you can also use the full expression without [just] if you prefer: + +``` +VALGRINDFLAGS="--suppressions=valgrind_suppressions.supp" cargo valgrind test --all-targets +``` + +## MIRI + +A subset of tests is also run under MIRI, which is even more strict than +Valgrind, but also cannot run all tests. + +You can run the relevant tests under MIRI with: + +``` +MIRIFLAGS=-Zmiri-disable-isolation cargo +nightly miri test +``` + +[insta]: https://insta.rs/ +[Valgrind]: https://valgrind.org/ +[just]: https://just.systems/man/en/ From ae8c7be8570df2cb9ca2e94530366896b16802c4 Mon Sep 17 00:00:00 2001 From: "Density 21.5" Date: Wed, 7 Jan 2026 15:01:16 +0100 Subject: [PATCH 2/5] add remarks about dev branch --- CONTRIBUTING.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db0932dd..59402fe6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -103,10 +103,11 @@ Before you start contributing code, ensure that the issue you are tackling has been properly discussed either on [Discourse] or the [issue tracker]. Do not submit pull requests for changes that have not been discussed. -You can contribute code by opening a pull request. Before you do you -should check that you code passes all tests and adheres to the [style -guide](#style-guide). You do not have to update `Changelog.md`. That will be -updated when a release is tagged. +You can contribute code by opening a pull request against the branch called +`dev`. Opening a PR against any other branch will have to be rebased to `dev`. +Before you do you should check that you code passes all tests and adheres to +the [style guide](#style-guide). You do not have to update `Changelog.md`. +That will be updated when a release is tagged. You run the code, you'll need to have a working and recent enough Rust toolchain installed. The [just] tool can also come in handy to run some common @@ -114,10 +115,14 @@ commands on this repository. Keep the following in mind while submitting your code: + - Work on a branch of your own created branched of the branch called `dev` in + our repository. + - Start the name of your branch with `feature-` or `bugfix-` or another + small functional description. Add a small description of the content of + the changes/additions, e.g. 'tcp-ao', so the full branch name would be + `feature-tcp-ao`. - Make sure to link the appropriate issue for your change. If there is none, make the issue and discuss the change before submitting the PR. - - Make the title and description descriptive. For example, do not make the - title just "Fix #345", but include a description. - Use descriptive commit messages. - Your code can only be merged once the CI is green. - Keep your PRs self-contained and do not include unrelated changes. It's From 202602c3c9abb4004ef7c57225c46e44a79e6052 Mon Sep 17 00:00:00 2001 From: Luuk Hendriks Date: Thu, 22 Jan 2026 08:49:02 +0100 Subject: [PATCH 3/5] Grammar/nits --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59402fe6..fe2681a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ See [SECURITY.md]. ### Reporting other bugs If you find something that is clearly a bug, you can submit it directly to the -issue tracker. Please look though existing issues before creating a new issue. +issue tracker. Please look through existing issues before creating a new issue. You should also check whether your issue has already been addressed on the `main` branch. @@ -60,7 +60,7 @@ creator(s) or those who have been assigned copyright by the original author(s). By submitting a patch to Rotonda, you are assumed to have the right to -the code and to be allowed by your employer or whatever to hand over that +the code and to be allowed by your employer or whomever to hand over that patch/code to us. We will credit you for your changes as far as possible, to give credit but also to keep a trace back to who made what changes. @@ -69,13 +69,13 @@ give credit but also to keep a trace back to who made what changes. Writing documentation is very hard, but _very_ appreciated. Improving the documentation could mean anything from adding new chapters to fixing a typo. The documentation of Rotonda has a repository of its -[own](https://github.com/nlnetLabs/rotonda-doc). +[own](https://github.com/NLnetLabs/rotonda-doc). - Go to the `/manual/docs/` folder of this repository. The documentation in the `/manual/docs/` folder is written in -[reStructuredText] and hosted [ReadTheDocs] via [Sphinx]. If you have the [uv] -tool installed, you can easily build the documentation locally with +[reStructuredText] and hosted on [ReadTheDocs] via [Sphinx]. If you have the +[uv] tool installed, you can easily build the documentation locally with ``` make html @@ -140,7 +140,7 @@ generated by `rustc`. Rotonda tries to minimize on `unsafe` code. This is not to say that we don't rely on `unsafe` code, but we are trying to isolate it in separate crates as much as possible, i.e. the `routedb` crate. If you really must use `unsafe` -code, we require that Valgrind does not raise any issues on test suite. Each +code, we require that Valgrind does not raise any issues on testing. Each `unsafe` block be accompanied by a `SAFETY` comment and each `unsafe` function should have a "Safety" section in its documentation. We generally do not rely on `unsafe` just to achieve better performance. From a289bfc18aed923d31842a7d6c86b19a3f030256 Mon Sep 17 00:00:00 2001 From: Luuk Hendriks Date: Thu, 22 Jan 2026 09:01:37 +0100 Subject: [PATCH 4/5] Use ordered lists, plus some grammar/nits --- RELEASING.md | 83 ++++++++++++++++++++++++++-------------------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index bca1ab1f..4a53f6c0 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -5,59 +5,60 @@ For a final release the workflow is the same as for an RC. Just leave out the A. CREATE RELEASE BRANCH - * create release branch with name release-x.y.0-rcz, e.g. release-0.1.0-rc0. - Note: we start counting at ZERO for the rc, and there's no '.' or '-' in - between rc and the number. - * Update [package] version field in Cargo.toml (e.g. version = "0.1.0-rc0"). - * Finalize Changelog.md: - * Add release date in the form "Released yyyy-mm-dd.". Note the dot at the - end. - * Remove unused sections. - * Review & update dependencies in `Cargo.toml`. - * Run `cargo update` - * If the previous step actually updated any crates, run `cargo check - --all-features --tests --release --examples`. If there are any warnings - and/or errors, fix them and go back to step A.4. - * [library only] Run cargo +nightly test -Z minimal-versions --release - --all-features. If there are any warnings and/or errors, fix them and go - back to step A.4. - * Add and commit changes to this release branch. - * Run `cargo package`. This will try building the crate locally, and will - output warnings and/or errors. If there are any, fix those, and add & - commit these fixes. Run cargo package again to see if they are actually - fixed. - * Push changes to GitHub (e.g. `git push --set-upstream origin release-0.1.i - 0-rc0`). + 1. Create a release branch named release-x.y.0-rcz, e.g. release-0.1.0-rc0. + Note: we start counting at ZERO for the rc, and there's no '.' or '-' in + between rc and the number. + 2. Update the [package] version field in Cargo.toml + (e.g. version = "0.1.0-rc0"). + 3. Finalize Changelog.md: + * Add release date in the form "Released yyyy-mm-dd.". Note the dot at + the end. + * Remove unused sections. + 4. Review & update dependencies in `Cargo.toml`. + 5. Run `cargo update` + 6. If the previous step actually updated any crates, run `cargo check + --all-features --tests --release --examples`. If there are any warnings + and/or errors, fix them and go back to step A.4. + 7. [library only] Run cargo +nightly test -Z minimal-versions --release + --all-features. If there are any warnings and/or errors, fix them and go + back to step A.4. + 8. Add and commit changes to this release branch. + 9. Run `cargo package`. This will try building the crate locally, and will + output warnings and/or errors. If there are any, fix those, and add & + commit these fixes. Run cargo package again to see if they are actually + fixed. + 10. Push changes to GitHub + (e.g. `git push --set-upstream origin release-0.1.i 0-rc0`). B. CREATE PULL REQUEST - * Create pull request on GitHub main ← release-x.y.0-rcz and wait for CI - to finish. - * Merge pull request. Add the changes for the release from Changelog.md as - the commit message body (the GitHub web UI lets you do this). + 1. Create pull request on GitHub main ← release-x.y.0-rcz and wait for CI to + finish. + 2. Merge pull request. Add the changes for the release from Changelog.md as + the commit message body (the GitHub web UI lets you do this). C. TAG ON BRANCH MAIN AND RELEASE PACKAGE - * Check out branch `main` and pull - * Double-check `Cargo.toml` and `Changelog.md`. - * Run `cargo publish` - * Create and push release tag with tag of form vx.y.0-rcz, e.g. `git tag -a - v0.1.0-rc0`. - * Add the changes for the release from Changelog.md as the tag message body - (Same as the merge commit message from the previous PR). - * Push the tag to GitHub (e.g. `git push --tags`). - * [Application Only] Create a release on GitHub. + 1. Check out branch `main` and pull. + 2. Double-check `Cargo.toml` and `Changelog.md`. + 3. Run `cargo publish`. + 4. Create and push release tag with tag of form vx.y.0-rcz, e.g. `git tag -a + v0.1.0-rc0`. + 5. Add the changes for the release from Changelog.md as the tag message body + (same as the merge commit message from the previous PR). + 6. Push the tag to GitHub (e.g. `git push --tags`). + 7. [Application Only] Create a release on GitHub. D. CREATE POST RELEASE COMMIT - * Still in branch `main`. Add new section to `Changelog.md` called - Unreleased new version. - * `Cargo.toml`: Increase version. - * [Application Only] Cargo.lock: Run cargo update -p , - e.g. `cargo update -p rotonda` + 1. Still in branch `main`. Add new section to `Changelog.md` called + Unreleased new version. + 2. `Cargo.toml`: Increase version (e.g. 0.1.1-dev). + 3. [Application Only] Cargo.lock: Run cargo update -p , + e.g. `cargo update -p rotonda` E. CREATE PACKAGES ON PACKAGES.NLNETLABS.NL From 7b43238bccd176da1248e8e030dc33a98682345f Mon Sep 17 00:00:00 2001 From: Luuk Hendriks Date: Thu, 22 Jan 2026 12:00:33 +0100 Subject: [PATCH 5/5] Some actual changes to the text --- CONTRIBUTING.md | 12 +++++------ TESTING.md | 53 +++++++++++++++---------------------------------- 2 files changed, 22 insertions(+), 43 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe2681a8..d8a156a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,8 +74,8 @@ fixing a typo. The documentation of Rotonda has a repository of its - Go to the `/manual/docs/` folder of this repository. The documentation in the `/manual/docs/` folder is written in -[reStructuredText] and hosted on [ReadTheDocs] via [Sphinx]. If you have the -[uv] tool installed, you can easily build the documentation locally with +[reStructuredText] and hosted on [ReadTheDocs] via [Sphinx]. You can easily +build the documentation locally with ``` make html @@ -140,10 +140,10 @@ generated by `rustc`. Rotonda tries to minimize on `unsafe` code. This is not to say that we don't rely on `unsafe` code, but we are trying to isolate it in separate crates as much as possible, i.e. the `routedb` crate. If you really must use `unsafe` -code, we require that Valgrind does not raise any issues on testing. Each -`unsafe` block be accompanied by a `SAFETY` comment and each `unsafe` function -should have a "Safety" section in its documentation. We generally do not rely -on `unsafe` just to achieve better performance. +code, we require that Valgrind and Miri do not raise any issues on testing. +Each `unsafe` block must be accompanied by a `SAFETY` comment and each `unsafe` +function should have a "Safety" section in its documentation. We generally do +not rely on `unsafe` just to achieve better performance. ## Maintainance diff --git a/TESTING.md b/TESTING.md index d25912bf..9dee6e97 100644 --- a/TESTING.md +++ b/TESTING.md @@ -2,52 +2,31 @@ The tests of Rotonda live in a few places: - - the `/tests` - unit tests in the source code - doctests in the source code + - end-to-end tests in a separate, private repo called REEDS + Running these tests is done with a single command: ``` cargo test --all-features --release ``` -Use with `cargo nextest` is probably possible, but, well, untested. - -## Snapshot testing - -Some of the tests use snapshot testing using [insta]. You can run -them with the regular Rust test runner, but to change them, you might want to -install `cargo-insta` with `cargo install cargo-insta`. See the [insta] website for more information. - -## Valgrind - -If you want to submit `unsafe` code to Rotonda, we require that the entire -test suite is run under [Valgrind]. To do that locally, you'll need to install -Valgrind and `cargo-valgrind`. - -If you have [just] installed, you can run the test suite under valgrind with - -``` -just valgrind -``` - -But you can also use the full expression without [just] if you prefer: - -``` -VALGRINDFLAGS="--suppressions=valgrind_suppressions.supp" cargo valgrind test --all-targets -``` - -## MIRI -A subset of tests is also run under MIRI, which is even more strict than -Valgrind, but also cannot run all tests. +## End-to-end testing (REEDS) -You can run the relevant tests under MIRI with: +The end-to-end tests for Rotonda are maintained in a separate repository that +is private. Keeping it private enables us to store real-world network data, +which is used as input in the test suites. -``` -MIRIFLAGS=-Zmiri-disable-isolation cargo +nightly miri test -``` +While this makes the end-to-end tests invisible, we do encourage contributors +to think about what types of input data would be required to test their +contributions in an end-to-end fashion. For example, when a PR adds certain new +fields to the response of an API endpoint, we should create a test where the +input (e.g. pcap or binary BMP) contains PDUs that result in API responses +featuring the newly added output. -[insta]: https://insta.rs/ -[Valgrind]: https://valgrind.org/ -[just]: https://just.systems/man/en/ +Ideally, a PR is accompanied with a pcap or likewise (perhaps transferred to +use in private) for us to create an end-to-end test from. This might not always +be trivial: in that case, please reach out to discuss how we can proceed to get +proper testing in place.