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 🌟
  • Hatch 🏗️
  • Install pre-commit to enforce code quality standards before pushing changes:
  • Pre-commit installation guide ✅
  • More about pre-commit hooks
  • If using VS Code, consider installing these extensions to automatically enforce formatting:
  • Ruff – Python linting & formatting 🐾
  • Markdownlint – Markdown linting (for documentation) ✍️
  • Git Hooks – 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 📦

It is recommended to set up a virtual environment before installing dependencies.

  • Using UV:
uv add --dev .[dev]
  • Using Hatch:
hatch env create dev
  • Using Standard Python:
python3 -m venv myenv
source myenv/bin/activate  # macOS/Linux
myenv\Scripts\activate    # Windows
pip install -e ".[dev]"

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:
pre-commit run
  • Run tests to ensure your contribution does not break functionality:
pytest --cov
  • If using UV: uv run pytest --cov

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:

    mkdocs serve
uv run mkdocs serve #If using uv

  • 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! 🎉