Skip to content

Latest commit

 

History

History
141 lines (94 loc) · 4.51 KB

CONTRIBUTING.md

File metadata and controls

141 lines (94 loc) · 4.51 KB

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:
  • Install pre-commit to enforce code quality standards before pushing changes:
  • 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

  3. Create a new branch with a descriptive name:

    git checkout -b feature-name

  4. 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

  2. Open a pull request (PR):

Thank you again for your contribution! 🎉