Skip to content

Contributing to mesa-frames 🚀

Thank you for taking the time to contribute to mesa-frames! Since the project is still in its early stages, we warmly welcome contributions that will help shape its development. 🎉

For a more general and comprehensive guide, please refer to mesa's main contribution guidelines. 📜

Project Roadmap 🗺️

Before contributing, we recommend reviewing our roadmap file to understand the project's current priorities, upcoming features, and long-term vision. This will help ensure your contributions align with the project's direction.

How to Contribute 💡

1. Prerequisite Installations ⚙️

Before you begin contributing, ensure that you have the necessary tools installed:

  • Install Python (at least the version specified in requires-python of pyproject.toml). 🐍

-- We recommend using a virtual environment manager like:

- [Astral's UV](https://docs.astral.sh/uv/#installation) 🌟
- [Hatch](https://hatch.pypa.io/latest/install/) 🏗️

-- If using VS Code, consider installing these extensions to automatically enforce formatting:

- [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) – Python linting & formatting 🐾
- [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) – Markdown linting (for documentation) ✍️
- [Git Hooks](https://marketplace.visualstudio.com/items?itemName=lakshmikanthayyadevara.githooks) – Automatically runs & visualizes pre-commit hooks 🔗

2. Contribution Process 🛠️

Step 1: Choose an Issue 📌

  • Pick an existing issue or create a new one if necessary.
  • Ensure that your contribution aligns with the project's goals.

Step 2: Set Up Your Local Repository 💻

  1. Fork the repository on GitHub.
  2. Clone your fork to your local machine:
git clone https://github.com/YOUR_USERNAME/mesa-frames.git
  1. Create a new branch with a descriptive name:
git checkout -b feature-name
  1. Prevent merge commit clutter by setting rebase mode:
git config pull.rebase true

Step 3: Install Dependencies 📦

We manage the development environment with uv:

uv sync --all-extras

This creates .venv/ and installs mesa-frames with the development extras.

Step 4: Make and Commit Changes ✨

  1. Make necessary edits and save the code.
  2. Add and commit your changes with meaningful commit messages:
git add FILE_NAME
git commit -m "Fix issue X: Brief description of the fix"

Step 5: Code Quality and Testing ✅

  • Run pre-commit hooks to enforce code quality standards:
uv run pre-commit run -a
  • Run tests to ensure your contribution does not break functionality:
uv run pytest -q --cov=mesa_frames --cov-report=term-missing

-- Optional: Runtime Type Checking (beartype) 🔍

You can enable stricter runtime validation of function arguments/returns with beartype during local development:

MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest -q --cov=mesa_frames --cov-report=term-missing

Quick facts:

  • Automatically enabled in: Hatch dev env (hatch shell dev), VS Code debugger, and VS Code test runs.
  • Enable manually by exporting MESA_FRAMES_RUNTIME_TYPECHECKING=1 (any of 1/true/yes).
  • Use only for development/debugging; adds overhead—disable for performance measurements or large simulations.
  • Unset with your shell (e.g. unset/Remove-Item Env: depending on shell) to turn it off.

Example for a one-off test run:

MESA_FRAMES_RUNTIME_TYPECHECKING=1 uv run pytest -q

Step 6: Documentation Updates (If Needed) 📖

  • If you add a new feature, update the documentation accordingly.
  • We use MKDocs for documentation:
  • Modify or create markdown files in the docs/ folder.

  • Preview your changes by running:

    uv run mkdocs serve

  • Open http://127.0.0.1:8000 in your browser to verify documentation updates.

Step 7: Push Changes and Open a Pull Request (PR) 🚀

  1. Push your changes to your fork:
git push origin feature-name
  1. Open a pull request (PR):
  2. Follow GitHub’s PR guide.
  3. Link the issue you are solving in the PR description.

Thank you again for your contribution! 🎉