mirror of https://codeberg.org/topola/topola.git
137 lines
3.9 KiB
Markdown
137 lines
3.9 KiB
Markdown
# 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](https://matrix.to/#/%23topola:tchncs.de) or [IRC
|
|
channel](https://webchat.oftc.net/?channels=#topola) 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](https://codeberg.org/topola/topola/issues).
|
|
|
|
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](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/).
|
|
|
|
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](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. Follow the instructions in above links
|
|
to obtain these.
|
|
|
|
#### Obtaining the source
|
|
|
|
Clone the [repository](https://codeberg.org/topola/topola):
|
|
|
|
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](https://trunkrs.dev/), 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](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
|
|
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/](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
|