topola/CONTRIBUTING.md

Contributing to Topola

Anyone can contribute to Topola, including you.

Contributions can be of any kind: documentation, organization, tutorials, blog posts, bug reports, issues, feature requests, feature implementations, pull requests, helping to manage issues, etc.. Many of these tasks do not require specialized programming knowledge, or any programming at all.

Chat

You are encouraged to join our Matrix chatroom or IRC channel to talk with us before you contribute. Both chatrooms are bridged, so it does not matter which one you join.

Reporting issues

If you believe you have found a defect in Topola or its documentation, please report it on our issue tracker.

Under normal operation, crashes and panics are always considered reportable bugs.

Writing code

We welcome code from anyone regardless of skill or experience level. We are friendly to newcomers. We will help you with your contribution if there are any problems.

Topola accepts contributions via pull requests. For a step-by-step guide on how to use these, refer to Codeberg's documentation.

Before you submit a pull request, make sure Topola actually builds with your changes. Follow the build instructions from the next section.

Building

Prerequisites

Building Topola from source requires git and cargo to be installed on your system. Follow the instructions in above links to obtain these.

Obtaining the source

Clone the repository:

git clone https://codeberg.org/topola/topola.git

Preparing to build

Change your working directory to your clone of Topola's repository:

cd topola

Egui port

Build the project with

cargo build --features "egui,disable_contracts" --bin topola-egui

Finally, run Topola by executing

cargo run --features "egui,disable_contracts" --bin topola-egui

Running Topola in a Web browser

Topola can be built to run in a Web browser using Trunk, which will be installed with the following command:

cargo binstall trunk

To build and open Topola in your browser, run

trunk serve

SDL2 demo

Optionally, for shorter build times you may build the SDL2 demo instead of the Egui port:

cargo build --features sdl2 --bin topola-sdl2-demo	
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 (yes, this Wikipedia article needs improvement), which are nothing else but slightly enchanced assertions.

Unfortunately, the contracts library which we have been using enforces post-conditions via closures, which have deal-breaking limitations. To bypass these we have forked and modified it to use try blocks instead. The fork is vendored in the 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