Contributing to UTPM

November 15, 2025 ยท View on GitHub

Thank you for your interest in contributing to UTPM! This document provides guidelines and standards for contributing to the project.

Code Standards

Formatting

UTPM uses rustfmt to ensure consistent code formatting across the project.

Before submitting a PR:

# Format your code
cargo fmt --all

# Or use just
just fmt

To check formatting without changes:

cargo fmt --all -- --check
# Or
just fmt-check

Configuration is in rustfmt.toml.

Linting

UTPM uses Clippy to catch common mistakes and enforce best practices.

Run Clippy:

cargo clippy --all-targets --all-features -- -D warnings
# Or
just clippy

Auto-fix Clippy issues:

cargo clippy --all-targets --all-features --fix --allow-dirty
# Or
just clippy-fix

Configuration is in clippy.toml.

Testing

All new features and bug fixes should include tests.

Run tests:

cargo test --all-features
# Or
just test

Run tests with output:

cargo test --all-features -- --nocapture
# Or
just test-verbose

See Testing Guide for comprehensive testing documentation, including:

  • Test structure and categories
  • Writing new tests
  • Running specific test suites
  • Test helpers and utilities
  • Debugging tests

Development Workflow

1. Setup

# Clone the repository
git clone https://github.com/typst-community/utpm.git
cd utpm

# Install git hooks (optional but recommended)
just setup-hooks

The git hooks will automatically run formatting checks, Clippy, and tests before each commit.

2. Making Changes

  1. Create a new branch for your feature/fix:

    git checkout -b feature/my-awesome-feature

  2. Make your changes following the code standards

  3. Format and lint your code:

    just fix  # Auto-format and fix Clippy issues

  4. Run tests:

    just test

  5. Commit your changes:

    git add .
git commit -m "feat: add my awesome feature"

3. Before Submitting a PR

Run all checks to ensure your code is ready:

just ci

This will run:

  • Format check (cargo fmt -- --check)
  • Clippy (cargo clippy)
  • Tests (cargo test)

4. Submitting a Pull Request

  1. Push your branch:

    git push origin feature/my-awesome-feature

  2. Open a Pull Request on GitHub

  3. Ensure all CI checks pass

  4. Address any review feedback

Commit Message Format

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, missing semicolons, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Maintenance tasks
  • ci: CI/CD changes

Examples:

feat(metadata): add command to extract typst.toml metadata
fix(link): respect typst_ignore flag when linking packages
docs: update README with metadata command examples
chore: add rustfmt and clippy configuration

Code Organization

Project Structure

See the source code and comments for detailed project architecture and patterns.

Key principles:

  • All commands are in src/commands/
  • Utilities are in src/utils/
  • Use utpm_log! for logging
  • Use utpm_bail! for errors
  • Check get_dry_run() before file operations
  • All command functions are async

Adding a New Command

  1. Create src/commands/new_command.rs
  2. Add to src/commands.rs (module declaration and args struct)
  3. Add to command enum in src/commands.rs
  4. Add dispatcher in src/main.rs
  5. Add tests
  6. Update documentation (README.md, CONTRIBUTING.md, DEVELOPMENT.md)

See the Metadata command as a reference implementation.

Tools and Utilities

Just Commands

We use just as a command runner. Install it:

cargo install just

Available commands:

just --list          # Show all available commands
just fmt             # Format code
just clippy          # Run Clippy
just test            # Run tests
just ci              # Run all CI checks
just fix             # Auto-fix formatting and Clippy issues
just build-release   # Build in release mode
just install-local   # Install to ~/.cargo/bin
just setup-hooks     # Setup git hooks

Editor Configuration

An .editorconfig file is provided for consistent editor settings. Most modern editors support EditorConfig automatically or via plugins.

Getting Help

  • Issues: Open an issue on GitHub for bugs or feature requests
  • Discussions: Use GitHub Discussions for questions
  • Documentation: Check the source code for technical details

License

By contributing to UTPM, you agree that your contributions will be licensed under the MIT License.