contributing: explain how to enable contracts

CONTRIBUTING.md

@@ -25,14 +25,14 @@ tracker](https://codeberg.org/topola/topola/issues).
 Under normal operation, crashes and panics are always considered
 reportable bugs.
 
-## Code contribution
+## Writing code
 
-We welcome code contributions from anyone regardless of skill or
+We welcome code from anyone regardless of skill or experience level.
-experience level. We're friendly to newcomers. We will help you with
+We're friendly to newcomers. We will help you with your contribution if
-your contribution if there are any problems.
+there are any problems.
 
-Topola accepts contributions using pull requests. For a step-by-step
+Topola accepts contributions via pull requests. For a step-by-step guide
-guide on how to use these, refer to Codeberg's
+on how to use these, refer to Codeberg's
 [documentation](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/).
 
 Before you submit a pull request, make sure Topola actually builds with
@@ -45,7 +45,8 @@ your changes. Follow the build instructions from the next section.
 Building Topola from source requires
 [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and
 [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)
-to be installed on your system.
+to be installed on your system. Follow the instructions in above links
+to obtain these.
 
 #### Obtaining the source
 
@@ -59,19 +60,15 @@ Change your working directory to your clone of Topola's repository:
 
     cd topola
 
-Topola currently requires nightly Rust to build. Enable it with
-
-    rustup override set nightly
-
 #### Egui port
 
 Build the project with
 
-    cargo build --features egui --bin topola-egui	
+    cargo build --features "egui,disable_contracts" --bin topola-egui
 
 Finally, run Topola by executing
 
-    cargo run --features egui --bin topola-egui
+    cargo run --features "egui,disable_contracts" --bin topola-egui
 
 ##### Running Topola in a Web browser
 
@@ -94,3 +91,46 @@ of the Egui port:
     cargo run --features sdl2 --bin topola-sdl2-demo
 
 The downside is that the SDL2 demo's user interface is highly incomplete.
+
+
+#### Automated tests
+
+Topola has automated tests to make sure its basic functionalities work.
+To execute these, run
+
+    cargo test --features disable_contracts
+
+#### Contracts
+
+When trying to locate the source of a bug, it may be helpful to enable
+[contracts](https://en.wikipedia.org/wiki/Design_by_contract) (yes, this
+Wikipedia article needs improvement), which are nothing else but
+slightly enchanced assertions.
+
+Unfortunately, the
+[contracts](https://docs.rs/contracts/latest/contracts/) library which
+we have been using enforces post-conditions via closures, which have
+numerous limitations. To bypass these we have forked and modified it to
+use `try` blocks instead. The fork is vendored in the
+[vendored/contracts/](vendored/contracts/) directory.
+
+However, `try` blocks aren't present in stable Rust versions yet, so to
+use these you need to set up your toolchain to use a nightly version of
+Rust.
+
+##### Nightly Rust
+
+To use nightly Rust, run the following command:
+
+    rustup override set nightly
+
+You can go back to stable with
+
+    rustup override unset
+
+##### Enabling contracts
+
+To enable contracts, simply remove the `disable_contracts` feature from
+commands. For example, to build tests with contracts, simply run
+
+    cargo test

README.md

@@ -2,43 +2,77 @@
 
 Work-in-progress interactive topological router in Rust.
 
-The project is funded by the [NLnet Foundation](https://nlnet.nl/) through the [NGI0 Entrust](https://nlnet.nl/entrust/) fund.
+The project is funded by the [NLnet Foundation](https://nlnet.nl/) via
+the [NGI0 Entrust](https://nlnet.nl/entrust/) fund.
 
-<img src="./assets/ngi0_entrust_banner.svg" alt="NGI0 Entrust banner" width="200"/>
 <img src="./assets/nlnet_banner.png" alt="NLnet Foundation banner" width="200"/>
+<img src="./assets/ngi0_entrust_banner.svg" alt="NGI0 Entrust banner" width="200"/>
 
 ## Chat
 
-Join the official [Matrix chatroom](https://matrix.to/#/%23topola:tchncs.de) or [IRC channel](https://webchat.oftc.net/?channels=#topola) to talk with the developers. Both chatrooms are bridged, so it does not matter which one you join.
+Join the official [Matrix
+chatroom](https://matrix.to/#/%23topola:tchncs.de) or [IRC
+channel](https://webchat.oftc.net/?channels=#topola) to talk with the
+developers. Both chatrooms are bridged, so it does not matter which one
+you join.
 
 ## Contributing
 
-*Anyone* can contribute to Topola, including you. If you want to help us out, please follow
+*Anyone* can contribute to Topola, including you. If you want to help us
-our [Contribution guide](CONTRIBUTING.md).
+out, please follow our [Contribution guide](CONTRIBUTING.md).
 
-Our official repository is on [Codeberg](https://codeberg.org/topola/topola). We also have a
+Our official repository is on
-mirror repository on [GitHub](https://github.com/mikwielgus/topola).
+[Codeberg](https://codeberg.org/topola/topola). We also have a mirror
+repository on [GitHub](https://github.com/mikwielgus/topola).
 
 ## Licence
 
 Topola is licensed under the [MIT licence](LICENSE).
 
 ## Gallery
-![Animation. There's a rubber band-like trace following cursor, navigating a very simple maze. The maze and the trace are red, the background is solid black but also very slightly white and dark blue](./assets/interactive_routing.gif)
 
-![Animation showing a trace, behaving like a rubber band, routed around obstacles step by step. Attempted alternative paths and a guiding mesh are shown.](./assets/mesh_visualization.gif)
+![Animation. There's a rubber band-like trace following cursor,
+navigating a very simple maze. The maze and the trace are red, the
+background is solid black but also very slightly white and dark
+blue](./assets/interactive_routing.gif)
 
-![Animation. There are two upward barriers, with some space between tem, around which four rubberband traces, one over another, are wrapped. Enter mouse cursor. The cursor begins to stretch the left barrier to the right. As it's stretched, the traces cease to be wrapped around the right barrier, becoming "free". The traces and the barrier are two-dimensional and all solid red. The background is black but also very slightly white and blue.](./assets/unwrapping_bends.gif "Unwrapping bends")
+![Animation showing a trace, behaving like a rubber band, routed around
+obstacles step by step. Attempted alternative paths and a guiding mesh
+are shown.](./assets/mesh_visualization.gif)
 
-![This animation shows four traces wrapped around a vertical barrier like rubberbands. Computer
+![Animation. There are two upward barriers, with some space between tem,
-cursor appears and starts dragging the barrier's top end left and right, up and down, elastically
+around which four rubberband traces, one over another, are wrapped.
-stretching the barrier and having the traces continue being wrapped on the barrier regardless of
+Enter mouse cursor. The cursor begins to stretch the left barrier to the
-its position. The traces and the barrier are all solid red. The background is black but also very
+right. As it's stretched, the traces cease to be wrapped around the
-slightly white and blue.](./assets/dragging_with_bends.gif "Dragging with bends")
+right barrier, becoming "free". The traces and the barrier are
+two-dimensional and all solid red. The background is black but also very
+slightly white and blue.](./assets/unwrapping_bends.gif "Unwrapping
+bends")
 
-![Animation. There is an upward barrier in the middle and dots on the left and right of it, four each. A trace is drawn from the leftmost dot on the left to the rightmost dot on the right. Then a trace is drawn from the second leftmost dot on the left to the second rightmost dot on the right, displacing the previous trace so that there's space for the new one. Same happens for the remaining dots. The dots, traces and barrier are all solid red. The background is black but also very slightly white and blue.](./assets/shoving_around.gif "Shoving traces under other traces")
+![This animation shows four traces wrapped around a vertical barrier
+like rubberbands. Computer cursor appears and starts dragging the
+barrier's top end left and right, up and down, elastically stretching
+the barrier and having the traces continue being wrapped on the barrier
+regardless of its position. The traces and the barrier are all solid
+red. The background is black but also very slightly white and
+blue.](./assets/dragging_with_bends.gif "Dragging with bends")
 
-![Animation showing three red-colored traces pass around a barrier. Trace bends are not aligned to a grid unlike most PCB layouts these days (this is called "topological routing"). The traces and the barrier are all solid red. The background is black but also very
+![Animation. There is an upward barrier in the middle and dots on the
-slightly white and blue.](./assets/stacked_bends.png "Stacking bends")
+left and right of it, four each. A trace is drawn from the leftmost dot
+on the left to the rightmost dot on the right. Then a trace is drawn
+from the second leftmost dot on the left to the second rightmost dot on
+the right, displacing the previous trace so that there's space for the
+new one. Same happens for the remaining dots. The dots, traces and
+barrier are all solid red. The background is black but also very
+slightly white and blue.](./assets/shoving_around.gif "Shoving traces
+under other traces")
 
-![Animation showing a trace zigzagging around two barriers. The trace and the barriers are all solid red. The background is black but also very slightly white and blue.](./assets/zigzag.png "Zigzag")
+![Animation showing three red-colored traces pass around a barrier.
+Trace bends are not aligned to a grid unlike most PCB layouts these days
+(this is called "topological routing"). The traces and the barrier are
+all solid red. The background is black but also very slightly white and
+blue.](./assets/stacked_bends.png "Stacking bends")
+
+![Animation showing a trace zigzagging around two barriers. The trace
+and the barriers are all solid red. The background is black but also
+very slightly white and blue.](./assets/zigzag.png "Zigzag")