This project is not really intended to be used as a library, so the MSRV is the latest stable toolchain, and we aspire to keep all dependencies up-to-date.
scorarium-archiveprovides the project's data model and data persistencescorarium-clientprovides API clients for the external metadata sourcesscorariumis the web serverscorarium-testsprovides test fixtures for integration tests
It's a "usual" Rust project, so you can use cargo as normal:
cargo build
cargo run -- ...
# Serve an in-memory demo database for demo and testing purposes
cargo run -- --demo
# nextest is preferred over 'cargo test' for better speed; both will work
cargo nextest run
cargo fmt -- --config group_imports=StdExternalCrate,imports_granularity=Module
cargo clippy --all-targets --all-features
# pip install djlint
djlint --reformat --profile django --indent 4 --max-line-length 120 --format-css --format-js crates/scorarium/templates
# For updating or auditing dependencies
cargo install cargo-edit
cargo upgrade --dry-run --incompatibleDatabase queries use sqlx's compile-time checked macros. Normal builds need no database: the macros
read the query metadata checked in under .sqlx/. When you add or change a query or a migration,
regenerate that metadata against a migrated dev database and check in the result:
cargo install sqlx-cli --no-default-features --features sqlite
export DATABASE_URL=sqlite://target/dev.db
cargo sqlx database setup --source crates/scorarium-archive/migrations
cargo sqlx prepare --workspace -- --all-targets --all-featuresWhile DATABASE_URL is exported, the macros check queries against that live database instead of
.sqlx/, so schema mistakes surface immediately during development.
The scorarium-client tests replay cached API responses from fixtures/ instead of making live
requests, so the test suite can run in parallel offline with no rate limiting.
Re-record the fixtures against the live APIs when you add a request or want to check for drift:
SCORARIUM_TEST_RECORD_LIVE_API=1 cargo nextest run --all-features --test-threads 1Review the diff carefully before checking it in.
ISBN validation and hyphenation need the ISBN agency's range table, which the isbn crate embeds at
build time. The crate publishes a new date-suffixed patch version as the table changes, so
cargo update needs to be done periodically to keep the table up-to-date.
This project vendors and self-serves its Bootstrap assets. To update them, run the following script:
tools/vendor-assets.shThe CI pipeline builds a static musl binary and packages it into a Docker image. This is how you can build that image yourself:
# Fedora
sudo dnf install musl-gcc
# Ubuntu
sudo apt install musl-toolsrustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl
docker build --tag scorarium:dev .
docker run --user "$(id -u):$(id -g)" --volume ./data:/data --publish 3000:3000 scorarium:devCI publishes the image to ghcr.io/notgnoshi/scorarium, tagged latest on every push to the
default branch and vX.Y.Z with each release.
The compose.yaml at the repository root runs the public demo instance behind nginx-proxy and
acme-companion, which handle TLS.
To update a deployment:
docker compose pull
docker compose up -dThis project values tests, but does not prioritize complete test coverage. Tests are code that needs to be reviewed and maintained just as well as any other, so this project prioritizes test quality over quantity. When adding a new test, consider if that test is actually valuable and justifies its maintenance cost. The same goes for comments and documentation: don't just say what the code does, but why it does it; the audience of comments and documentation is not the developer at the time of writing, but the maintainer in several years.
To make a release, add an entry to the CHANGELOG.md file and then merge a PR that bumps the
version in the workspace Cargo.toml. The CI pipeline will do the rest. Not every change needs
mentioned in the changelog. Keep the focus on changes that are relevant to the end user.