Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (84 loc) · 3.46 KB

CONTRIBUTING.md

File metadata and controls

128 lines (84 loc) · 3.46 KB
Raw

Contributing to RustQueue

Thanks for your interest. RustQueue is an actively developed learning project being evolved into a solid, well-documented Rust job queue. Contributions are welcome -- but read this first so your time isn't wasted.

What we're looking for

Good contributions right now:

  • Bug fixes with a clear reproduction case
  • New job handler implementations (Telegram, HTTP webhook, etc.) following the existing JobHandler pattern
  • Documentation improvements (clearer explanations, better examples)
  • Test coverage (there is currently none -- this is a known gap)
  • Performance observations backed by benchmarks

Not a good fit right now:

  • Large architectural changes without prior discussion
  • Dependencies that bring significant weight for marginal benefit
  • Features not on the roadmap without prior discussion (open an issue first)

Branching model

main   -> always stable, always demo-able
dev    -> integration branch, features land here before main
feature/your-feature-name  -> your work
fix/your-fix-name          -> bug fixes

Always branch off dev, not main. PRs go into dev. When dev is stable it gets merged into main.

Getting started locally

git clone https://github.com/Ekojoecovenant/rustqueue.git
cd rustqueue
git checkout dev

cp .env.example .env
# fill in your credentials

sqlx migrate run
cargo check
cargo run

If cargo check fails on a clean clone, open an issue -- that's a bug on our side.

Making a change

  1. Branch off dev:

    git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

  2. Make your changes. Keep commits focused -- one logical change per commit.

  3. Run cargo check and cargo clippy before pushing. Don't submit PRs that don't compile.

  4. Push your branch and open a PR against dev (not main).

PR checklist

Before submitting:

  • Branches off dev, targets dev
  • cargo check passes
  • cargo clippy passes with no new warnings
  • New job handlers implement JobHandler and are registered in HandlerRegistry
  • New env variables are documented in .env.example
  • Migration files included if schema changes were made
  • PR description explains what changed and why

Adding a new job handler

This is the most common contribution type and the most welcome. The pattern is straightforward:

  1. Create src/executor/your_handler.rs
  2. Implement JobHandler for your struct
  3. Add a constructor that returns Result<Self> (can fail, e.g. if credentials are invalid)
  4. Register in HandlerRegistry::new() in src/executor/mod.rs
  5. Document the expected payload shape in the README

See src/executor/email.rs as a reference implementation.

Code style

  • Follow existing patterns rather than introducing new ones without discussion
  • Prefer anyhow for error handling in application code
  • Add .context("...") to every ? that could use a clearer error message
  • Keep functions focused -- if a function is doing more than one thing, split it
  • No unwrap() in paths that could realistically fail in production

Opening issues

If you found a bug, include:

  • What you expected to happen
  • What actually happened
  • Steps to reproduce
  • Relevant logs or error messages

If you have a feature idea, describe the problem it solves before describing the solution.

License

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