Contributing to Lumina#

IMPORTANT

This project is primarily hosted on Codeberg.

Thank you for your interest in contributing! This document outlines how to set up your environment, follow the style, and submit changes.

Where to contribute#

• Main repository (primary): https://codeberg.org/strawmelonjuice/Lumina
• Official mirror 1:https://git.strawmelonjuice.com/strawmelonjuice/Lumina
• Official mirror 2: https://github.com/strawmelonjuice/lumina

Please open issues and submit pull requests (PRs) on the main repository or an official mirror.

Code of Conduct#

• Be respectful and constructive.
• Assume good intent and seek clarity.
• Harassment, discrimination, and personal attacks are not tolerated.

If you experience or witness unacceptable behavior, contact the maintainer via the main forge.

Project layout#

• server/ — Rust (Rocket) server application.
• client/ — Gleam application targeting JavaScript (bundled to browser).
• mise/ — Task definitions for development flows.
• data/ — Local runtime data directory (created by tasks).
• Root files — Workspace-level configuration, licence, docs, and Docker-related files.

Prerequisites#

• Rust toolchain (latest stable) with rustfmt and (optionally) clippy.
• Gleam.
• Bun.
• Node is not required when using Bun.
• Redis/Postgres if you want to test those backends, otherwise SQLite is the default for development.
• Optional: Watchexec (installed automatically via tasks), Taplo, Prettier (run via tasks).

This repository uses mise to manage tools and developer tasks:

• Install mise: https://mise.jdx.dev/
• Then install toolchain/tool deps used by the project and tasks:

  mise install
  

Local setup#

Local setup is pretty easy with mise, and to not do it with mise is actually kind of unthinkable for me at this point.

Typical preparation:

# From repo root
mise install
mise run build-env-image-podman # Build the environment image for podman, allowing you to build quicker.
# And then later:
mise run devel # or devel-watch

Running in the typical dev pod allows you to also access PGWeb on http://127.0.0.1:8081 and Redis Commander on http://127.0.0.1:8082.

Running 'bare-metal' is usually prepared as well, since we need a database:

# From repo root
mise install
mise run local-devel-prep # Because you'll need a database running somewhere.
# And then later:
mise run local-devel # or local-devel-watch
# To have the tools from the pod development environment available on your host machine, run:
mise run local-devel-dataexplorer # For PGWeb and Redis Commander on host machine.

This means everything is still running in podman, except for lumina itself, which runs on your host machine. This sometimes speeds up build speeds.

The README should have some environment variables you could set.

There are more variations. Run mise run to list all of them.

The build pipeline (mise) takes care of client (Gleam) compilation and styles, and it will create necessary data directories.

When running Lumina server in devel mode, it automatically creates two accounts for you and one of those has an attached post on the global timeline.

Formatting, checks, and quality#

Before pushing or opening a PR, run:

# Format Rust, Gleam, and meta files
mise run format

# Basic checks (Rust and Gleam)
mise run check

# Build to ensure it compiles
mise run build-server

# Optionally: There are some watching tasks and tasks to run Lumina in development mode
mise run check-watch
mise run devel
# ..etc.

Conventions:

• Rust code is formatted with rustfmt.
• Gleam code is formatted with gleam format.
• Meta files are formatted via Prettier and Taplo.
• Prefer clear, explicit error handling and logs over silent failures.
• Keep modules cohesive and prefer small, testable units.

Branching and commit messages#

• Create feature branches from the default branch (typically main).
  • Suggested naming: feat/<short-name>, fix/<short-name>, docs/<short-name>, chore/<short-name>.
• Commit messages:
  • Be concise and descriptive.
  • Prefer Conventional Commits style when possible:
    • feat: add user session cleanup job
    • fix(server): handle empty redis url
    • docs: improve contributing guide

Pull requests#

PR checklist:

• Code is formatted and builds locally.
• mise run check passes.
• Include tests when adding logic or fixing bugs (Rust: cargo test; Gleam: gleam test).
• Update docs (README/WHY/ABOUT) where relevant.
• Keep PRs focused. Large refactors should be split or well-justified.

Review expectations:

• Be prepared to discuss design decisions and trade-offs.
• Address review comments via additional commits (avoid force-push unless asked).
• Squash commits at merge time if appropriate.

Reporting bugs#

When filing a bug report:

• Describe what you expected to happen and what actually happened.
• Include steps to reproduce.
• Provide version info (commit hash) and environment (OS, DB type, Redis/Postgres versions).
• Include relevant logs or stack traces when possible.

Feature requests#

When proposing a feature:

• Explain the problem it solves and the target use-cases.
• Consider alternatives and why this approach is preferred.
• If possible, include a small design sketch (API, data flow, or UI).
• Prototype branches are welcome if they help the discussion.

Security#

If you discover a security issue:

• Do not open a public issue with sensitive details.
• Contact me privately via the email on my main forge.
• Provide clear reproduction steps and affected versions.
• A fix or mitigation plan will be discussed before public disclosure.

Tests#

• Rust: place tests alongside modules or in server/ integration tests, use cargo test.
• Gleam: use gleam test for client-side logic where applicable.
• Prefer deterministic tests; avoid timing-based flakes.
• Add tests for new behavior and regression tests for fixed bugs.

Licence and contributor terms#

By contributing, you agree that your contributions are licensed under the AGPLv3 Licence of this repository, unless explicitly stated otherwise in writing.

See COPYING at the repository root.

Thank you#

Your time and effort are appreciated. Whether you’re reporting a bug, improving docs, or adding features—every contribution helps make Lumina better.