|
| 1 | +# Contributing to `mcpd-plugins-sdk-python` |
| 2 | + |
| 3 | +Thank you for your interest in contributing to the `mcpd` project! |
| 4 | +We welcome contributions from everyone and are grateful for your help in making this project better. |
| 5 | + |
| 6 | +By contributing to this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## **Guidelines for Contributions** |
| 11 | + |
| 12 | +### Ground Rules |
| 13 | + |
| 14 | +- Review issue discussion fully before starting work. Engage in the thread first when an issue is under discussion. |
| 15 | +- PRs must build on agreed direction where ones exist. If there is no agreed direction, seek consensus from the core maintainers. |
| 16 | +- PRs with "drive-by" unrelated changes or untested refactors will be closed. |
| 17 | +- Untested or failing code is not eligible for review. |
| 18 | +- PR description **must** follow the PR template and explain **what** changed, **why**, and **how to test**. |
| 19 | +- Links to related issues are required. |
| 20 | +- Duplicate PRs will be automatically closed. |
| 21 | +- Only have 1-2 PRs open at a time. Any further PRs will be closed. |
| 22 | + |
| 23 | +**Maintainers reserve the right to close issues and PRs that do not align with the library roadmap.** |
| 24 | + |
| 25 | +### Code Clarity and Style |
| 26 | + |
| 27 | +- **Readability first:** Code must be self-documenting—if it is not self-explanatory, it should include clear, concise comments where logic is non-obvious. |
| 28 | +- **Consistent Style:** Follow existing codebase style (e.g., function naming, Python conventions). |
| 29 | +- **No dead/debug code:** Remove commented-out blocks, leftover debug statements, unrelated refactors. |
| 30 | +- Failure modes must be documented and handled with robust error handling. |
| 31 | + |
| 32 | +### Testing Requirements |
| 33 | + |
| 34 | +- **Coverage:** All new functionality must include unit tests covering both happy paths and relevant edge cases. |
| 35 | +- **Passing tests:** All linting and formatting checks must pass (see below on how to run). |
| 36 | +- **No silent failures:** Tests should fail loudly on errors. No placeholder tests. |
| 37 | + |
| 38 | +### Scope and Size |
| 39 | + |
| 40 | +- **One purpose per PR:** No kitchen-sink PRs mixing bugfixes, refactors, and features. |
| 41 | +- **Small, reviewable chunks:** If your PR is too large to review in under 30 minutes, break it up into chunks. |
| 42 | +- Each chunk must be independently testable and reviewable |
| 43 | +- If you can't explain why it can't be split, expect an automatic request for refactoring. |
| 44 | +- Pull requests that are **large** (>500 LOC changed) or span multiple subsystems will be closed with automatic requests for refactoring. |
| 45 | +- If the PR is to implement a new feature, please first make a GitHub issue to suggest the feature and allow for discussion. We reserve the right to close feature implementations and request discussion via an issue. |
| 46 | + |
| 47 | +## How to Contribute |
| 48 | + |
| 49 | +### **Browse Existing Issues** 🔍 |
| 50 | +- Check the Issues page to see if there are any tasks you'd like to tackle. |
| 51 | +- Look for issues labeled **`good first issue`** if you're new to the project—they're a great place to start. |
| 52 | + |
| 53 | +### **Report Issues** 🐛 |
| 54 | +- **Bugs:** Please use our [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.yaml) to provide clear steps to reproduce and environment details. |
| 55 | +- **Search First:** Before creating a new issue, please search existing issues to see if your topic has already been discussed. |
| 56 | +- Provide as much detail as possible, including the steps to reproduce the issue and expected vs. actual behavior. |
| 57 | + |
| 58 | +### **Suggest Features** 🚀 |
| 59 | +- **Features:** Please use our [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.yaml) to describe the problem your idea solves and your proposed solution. |
| 60 | +- Share why the feature is important and any alternative solutions you've considered. |
| 61 | +- If the PR is to implement a new feature, please first make a GitHub issue to suggest the feature and allow for discussion. |
| 62 | + |
| 63 | +### Requirements |
| 64 | + |
| 65 | +* `make setup` |
| 66 | + |
| 67 | +### **Submit Pull Requests** 💻 |
| 68 | + |
| 69 | +1. **Fork** the repository on GitHub. |
| 70 | +2. **Clone** your forked repository to your local machine. |
| 71 | + ```bash |
| 72 | + git clone https://github.com/{YOUR_GITHUB_USERNAME}/mcpd-plugins-sdk-python.git |
| 73 | + cd mcpd-plugins-sdk-python |
| 74 | + ``` |
| 75 | +3. **Create a new branch** for your changes based on the `main` branch. |
| 76 | + ```bash |
| 77 | + git checkout main |
| 78 | + git pull origin main |
| 79 | + git checkout -b your-feature-or-bugfix-branch |
| 80 | + ``` |
| 81 | +4. **Format and Lint:** Ensure your code passes linting and formatting checks: |
| 82 | + ```bash |
| 83 | + make lint |
| 84 | + ``` |
| 85 | +5. **Add Unit Tests:** All new features and bug fixes should be accompanied by relevant unit tests. Run tests with: |
| 86 | + ```bash |
| 87 | + make test |
| 88 | + ``` |
| 89 | +6. **Commit your changes** with a clear and descriptive message. |
| 90 | + |
| 91 | +7. **Push your branch** to your forked repository. |
| 92 | + |
| 93 | +8. **Open a Pull Request** from your branch to the `main` branch of the upstream `mozilla-ai/mcpd-plugins-sdk-python` repository. |
| 94 | + - Follow the [Guidelines for Contributions](#guidelines-for-contributions) |
| 95 | + - Ensure your branch is up-to-date with the main branch before submitting the PR |
| 96 | + - Please follow the PR template, adding as much detail as possible, including how to test the changes |
| 97 | + - Reference the relevant GitHub issue in your PR summary |
| 98 | + |
| 99 | +> [!IMPORTANT] |
| 100 | +> Ensure that any related documentation is updated both in code comments and in markdown before submitting the PR. |
| 101 | + |
| 102 | +## Security Vulnerabilities |
| 103 | + |
| 104 | +If you discover a security vulnerability, please **DO NOT** open a public issue. Report it responsibly by following our [Security Policy](SECURITY.md). |
| 105 | + |
| 106 | +## License |
| 107 | + |
| 108 | +By contributing, you agree that your contributions will be licensed as described in [LICENSE](LICENSE.md). |
0 commit comments