Contributing to Loco

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• DEVELOPMENT.md
• README.md
• snipdoc.yml
• loco-cli/README.md
• docs-site/content/blog/frontend-website.md

Loco is a community-driven, productivity-first web and API framework for Rust, strongly inspired by Ruby on Rails. The project follows a "one-person framework" philosophy, prioritizing simplicity, stability, and high developer productivity by reducing boilerplate through sensible defaults and powerful CLI tools.

Contributing to Loco involves participating in discussions, requesting features, improving documentation, or submitting code changes via Pull Requests. The project emphasizes convention over configuration and provides a robust testing ground through example applications to ensure framework stability across various configurations.

Sources: CONTRIBUTING.md:1-10, README.md:19-30, docs-site/content/blog/hello-world.md

Development Workflow

Contributors are encouraged to use the examples/demo application as a testing ground, as it points to the latest local loco framework modifications. This allows for real-world validation of framework changes within an actual application context.

Local Environment Setup

Before running tests or developing new features, certain local resources must be available:

• Redis: Must be running for background job testing.
• Database: Necessary for ORM and migration testing.
• Starters: Frontend packages (like the SaaS starter) should be built using pnpm.

Sources: CONTRIBUTING.md:42-45, DEVELOPMENT.md:20-30

Code Style and Quality

Loco enforces strict code styling using rustfmt (nightly) and clippy. All workspace features and manifest paths must be checked to avoid warnings or idiomatic issues.

# Formatting
cargo fmt --all

# Linting
cargo clippy --fix --allow-dirty --workspace --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery -W rust-2018-idioms

Sources: CONTRIBUTING.md:48-64

Testing Architecture

Loco utilizes a multi-layered testing strategy to ensure framework reliability and prevent regressions in CLI output or API behavior.

Testing Components

Component	Tool / Method	Description
Unit/Integration	cargo test	Standard Rust test suite for core logic.
Snapshots	insta	Detects changes in output formats and behavior.
CLI Outputs	trycmd	Maintains snapshots of binary command outputs.
Integration App	examples/demo	Exercises the framework in a "driver app" environment.

Sources: CONTRIBUTING.md:66-82, DEVELOPMENT.md:50-55

Testing Flow

The following diagram illustrates the workflow for validating changes before submission:

Documentation System

Loco maintains documentation through a dual-component system designed to reduce duplication and ensure consistency between code and guides.

Documentation Components

1. loco.rs Website: Built using Zola, located in docs-site/.
2. RustDocs: Standard Rust API documentation.
3. Snipdoc: A tool used to manage code snippets across documentation and YAML files to prevent desynchronization.

Snipdoc Workflow

Snippets are defined in snipdoc.yml or inlined in code and injected into documentation using snipdoc run.

snippets:
  starting-the-server-command:
    content: cargo loco start
    path: ./snipdoc.yml

Sources: CONTRIBUTING.md:84-106, snipdoc.yml:1-45

Dependency Management and "Loco Doctor"

The loco doctor command is a critical maintenance tool that checks the health of the development environment. It validates "blessed" dependencies that exist both in the Loco core and in generated user applications.

Key Checks

• SeaORM CLI: Ensures version compatibility between the CLI and the framework.
• Axum: Validates the core web engine version.
• Resource Connections: Checks active connections to the Database and Redis.

Maintainers can update minimal version requirements in src/doctor.rs.
Sources: DEVELOPMENT.md:1-15, snipdoc.yml:93-100

Error Handling Standards

Loco adopts a minimalistic and informative approach to error handling using the thiserror crate.

• Opaque Errors: Used for errors that cannot be handled but need to be informative.
• Matchable Errors: Used for errors where logic needs to reason upon the failure.
• Contextual Data: Errors often wrap source errors with specialized types (e.g., YAMLFile) to include file paths or other metadata lost at the call site.

Release and Versioning Process

Releasing a new version of Loco involves a coordinated "bump" that aligns the framework with its starters.

Release Steps

1. Validation: Run cargo loco doctor --environment test.
2. Version Bump: Execute cargo xtask bump-version <version>. This updates the framework and starters simultaneously.
3. Starters Alignment: Starters CI uses fixed versions, so the framework must be published before starters can successfully pull the new version.
4. Publishing: cargo publish from the root.
5. Changelog: Move vnext entries to the new version section and create a new blank vnext.

Sources: DEVELOPMENT.md:57-85

Pull Request Guidelines

To be accepted, a Pull Request must:

• Be based on the master branch.
• Successfully pass the full test suite and adhere to defined code styles.
• Include informative notes regarding the necessity of the change.
• Reference any fixed bugs and explain the testing methodology used.

Sources: CONTRIBUTING.md:108-124

Loco thrives on community participation. By following these architectural and procedural guidelines, contributors help maintain the project's goal of being the premier "one-person framework" for the Rust ecosystem.