|
| 1 | +# Contributing to mesa-frames 🚀 |
| 2 | + |
| 3 | +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. 🎉 |
| 4 | + |
| 5 | +For a more general and comprehensive guide, please refer to [mesa's main contribution guidelines](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md). 📜 |
| 6 | + |
| 7 | +## Project Roadmap 🗺️ |
| 8 | + |
| 9 | +Before contributing, we recommend reviewing our [roadmap](https://projectmesa.github.io/mesa-frames/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. |
| 10 | + |
| 11 | +## How to Contribute 💡 |
| 12 | + |
| 13 | +### 1. Prerequisite Installations ⚙️ |
| 14 | + |
| 15 | +Before you begin contributing, ensure that you have the necessary tools installed: |
| 16 | + |
| 17 | +- **Install Python** (at least the version specified in `requires-python` of `pyproject.toml`). 🐍 |
| 18 | +- We recommend using a virtual environment manager like: |
| 19 | + - [Astral's UV](https://docs.astral.sh/uv/#installation) 🌟 |
| 20 | + - [Hatch](https://hatch.pypa.io/latest/install/) 🏗️ |
| 21 | +- Install **pre-commit** to enforce code quality standards before pushing changes: |
| 22 | + - [Pre-commit installation guide](https://pre-commit.com/#install) ✅ |
| 23 | + - [More about pre-commit hooks](https://stackoverflow.com/collectives/articles/71270196/how-to-use-pre-commit-to-automatically-correct-commits-and-merge-requests-with-g) |
| 24 | +- If using **VS Code**, consider installing these extensions to automatically enforce formatting: |
| 25 | + - [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) – Python linting & formatting 🐾 |
| 26 | + - [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) – Markdown linting (for documentation) ✍️ |
| 27 | + - [Git Hooks](https://marketplace.visualstudio.com/items?itemName=lakshmikanthayyadevara.githooks) – Automatically runs & visualizes pre-commit hooks 🔗 |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +### 2. Contribution Process 🛠️ |
| 32 | + |
| 33 | +#### **Step 1: Choose an Issue** 📌 |
| 34 | + |
| 35 | +- Pick an existing issue or create a new one if necessary. |
| 36 | +- Ensure that your contribution aligns with the project's goals. |
| 37 | + |
| 38 | +#### **Step 2: Set Up Your Local Repository** 💻 |
| 39 | + |
| 40 | +1. **Fork the repository** on GitHub. |
| 41 | +2. **Clone your fork** to your local machine: |
| 42 | + |
| 43 | + ```sh |
| 44 | + git clone https://github.com/YOUR_USERNAME/mesa-frames.git |
| 45 | + ``` |
| 46 | + |
| 47 | +3. **Create a new branch** with a descriptive name: |
| 48 | + |
| 49 | + ```sh |
| 50 | + git checkout -b feature-name |
| 51 | + ``` |
| 52 | + |
| 53 | +4. **Prevent merge commit clutter** by setting rebase mode: |
| 54 | + |
| 55 | + ```sh |
| 56 | + git config pull.rebase true |
| 57 | + ``` |
| 58 | + |
| 59 | +#### **Step 3: Install Dependencies** 📦 |
| 60 | + |
| 61 | +It is recommended to set up a virtual environment before installing dependencies. |
| 62 | + |
| 63 | +- **Using UV**: |
| 64 | + |
| 65 | + ```sh |
| 66 | + uv add --dev .[dev] |
| 67 | + ``` |
| 68 | + |
| 69 | +- **Using Hatch**: |
| 70 | + |
| 71 | + ```sh |
| 72 | + hatch env create dev |
| 73 | + ``` |
| 74 | + |
| 75 | +- **Using Standard Python**: |
| 76 | + |
| 77 | + ```sh |
| 78 | + python3 -m venv myenv |
| 79 | + source myenv/bin/activate # macOS/Linux |
| 80 | + myenv\Scripts\activate # Windows |
| 81 | + pip install -e ".[dev]" |
| 82 | + ``` |
| 83 | + |
| 84 | +#### **Step 4: Make and Commit Changes** ✨ |
| 85 | + |
| 86 | +1. Make necessary edits and save the code. |
| 87 | +2. **Add and commit** your changes with meaningful commit messages: |
| 88 | + |
| 89 | + ```sh |
| 90 | + git add FILE_NAME |
| 91 | + git commit -m "Fix issue X: Brief description of the fix" |
| 92 | + ``` |
| 93 | + |
| 94 | + - Keep commits **small and focused** on a single logical change. |
| 95 | + - Follow [Tim Pope’s commit message guidelines](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). 📝 |
| 96 | + |
| 97 | +#### **Step 5: Code Quality and Testing** ✅ |
| 98 | + |
| 99 | +- **Run pre-commit hooks** to enforce code quality standards: |
| 100 | + |
| 101 | + ```sh |
| 102 | + pre-commit run |
| 103 | + ``` |
| 104 | + |
| 105 | +- **Run tests** to ensure your contribution does not break functionality: |
| 106 | + |
| 107 | + ```sh |
| 108 | + pytest --cov |
| 109 | + ``` |
| 110 | + |
| 111 | + - If using UV: `uv run pytest --cov` |
| 112 | + |
| 113 | +#### **Step 6: Documentation Updates (If Needed)** 📖 |
| 114 | + |
| 115 | +- If you add a new feature, update the documentation accordingly. |
| 116 | +- We use **[MKDocs](https://www.mkdocs.org/)** for documentation: |
| 117 | + - Modify or create markdown files in the `docs/` folder. |
| 118 | + - Preview your changes by running: |
| 119 | + |
| 120 | + ```sh |
| 121 | + mkdocs serve |
| 122 | + uv run mkdocs serve #If using uv |
| 123 | + ``` |
| 124 | + |
| 125 | + - Open `http://127.0.0.1:8000` in your browser to verify documentation updates. |
| 126 | + |
| 127 | +#### **Step 7: Push Changes and Open a Pull Request (PR)** 🚀 |
| 128 | + |
| 129 | +1. **Push your changes** to your fork: |
| 130 | + |
| 131 | + ```sh |
| 132 | + git push origin feature-name |
| 133 | + ``` |
| 134 | + |
| 135 | +2. **Open a pull request (PR)**: |
| 136 | + - Follow [GitHub’s PR guide](https://help.github.com/articles/creating-a-pull-request/). |
| 137 | + - Link the issue you are solving in the PR description. |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +Thank you again for your contribution! 🎉 |
0 commit comments