|
| 1 | +# Contributing to Model API |
| 2 | + |
| 3 | +We welcome your input! 👐 |
| 4 | + |
| 5 | +We want to make it as simple and straightforward as possible to contribute to this project, whether it is a: |
| 6 | + |
| 7 | +- Bug Report |
| 8 | +- Discussion |
| 9 | +- Feature Request |
| 10 | +- Creating a Pull Request (PR) |
| 11 | +- Becoming a maintainer |
| 12 | + |
| 13 | +## Bug Report |
| 14 | + |
| 15 | +We use GitHub issues to track the bugs. Report a bug by using [Issues](https://github.com/open-edge-platform/model_api/issues/new) page. |
| 16 | + |
| 17 | +## Feature Request |
| 18 | + |
| 19 | +We utilize GitHub issues to track the feature requests as well. If you are certain regarding the feature you are interested and have a solid proposal, you could then create the feature request by [Issues](https://github.com/open-edge-platform/model_api/issues/new) page. |
| 20 | + |
| 21 | +## Development & PRs |
| 22 | + |
| 23 | +We actively welcome your pull requests: |
| 24 | + |
| 25 | +### Getting Started |
| 26 | + |
| 27 | +#### 1. Fork and Clone the Repository |
| 28 | + |
| 29 | +First, fork the Model API repository by following the GitHub documentation on [forking a repo](https://docs.github.com/en/enterprise-cloud@latest/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). Then, clone your forked repository to your local machine and create a new branch from `master`. |
| 30 | + |
| 31 | +#### 2. Set Up Your Development Environment |
| 32 | + |
| 33 | +Set up your development environment to start contributing. This involves installing the required dependencies and setting up pre-commit hooks for code quality checks. Note that this guide assumes you are using [Venv](https://docs.python.org/3/library/venv.html) for python environments management. However, the steps are similar for other env managers. |
| 34 | + |
| 35 | +<details> |
| 36 | +<summary>Development Environment Setup Instructions</summary> |
| 37 | + |
| 38 | +1. Create and activate a new python environment: |
| 39 | + |
| 40 | + ```bash |
| 41 | + python -m venv .mapi |
| 42 | + source .mapi/bin/activate |
| 43 | + ``` |
| 44 | + |
| 45 | +2. Install the development requirements: |
| 46 | + |
| 47 | + ```bash |
| 48 | + pip install -e ./src/python[full] |
| 49 | + ``` |
| 50 | + |
| 51 | +3. [Build](https://github.com/open-edge-platform/model_api?tab=readme-ov-file#c) C++ binaries |
| 52 | + |
| 53 | +Make sure to address any pre-commit issues before finalizing your pull request. |
| 54 | +Pre-commit checks can be launched by the command: |
| 55 | + |
| 56 | +```bash |
| 57 | +pre-commit run --all-files |
| 58 | +``` |
| 59 | + |
| 60 | +</details> |
| 61 | + |
| 62 | +### Making Changes |
| 63 | + |
| 64 | +1. **Write Code:** Follow the project's coding standards and write your code with clear intent. Ensure your code is well-documented and includes examples where appropriate. For code quality we use ruff, whose configuration is in [`pyproject.toml`](pyproject.toml) file. |
| 65 | + |
| 66 | +2. **Add Tests:** If your code includes new functionality, add corresponding tests using [pytest](https://docs.pytest.org/en/7.4.x/) to maintain coverage and reliability. |
| 67 | + |
| 68 | +3. **Update Documentation:** If you've changed APIs or added new features, update the documentation accordingly. Ensure your docstrings are clear and follow [Google's docstring guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). |
| 69 | + |
| 70 | +4. **Pass Tests and Quality Checks:** Ensure the test suite passes and that your code meets quality standards by running: |
| 71 | + |
| 72 | + ```bash |
| 73 | + pre-commit run --all-files |
| 74 | + python tests/cpp/precommit/prepare_data.py -d data -p tests/cpp/precommit/public_scope.json |
| 75 | + python tests/python/accuracy/prepare_data.py -d data |
| 76 | + pytest tests/python/ |
| 77 | + |
| 78 | + build/test_sanity -d data -p tests/cpp/precommit/public_scope.json && build/test_model_config -d data |
| 79 | + build/test_accuracy -d data -p tests/python/accuracy/public_scope.json |
| 80 | + ``` |
| 81 | + |
| 82 | +5. **Update the Changelog:** For significant changes, add a summary to the [CHANGELOG](CHANGELOG.md). |
| 83 | + |
| 84 | +6. **Check Licensing:** Ensure you own the code or have rights to use it, adhering to appropriate licensing. |
| 85 | + |
| 86 | +7. **Sign Your Commits:** Use signed commits to certify that you have the right to submit the code under the project's license: |
| 87 | + |
| 88 | + ```bash |
| 89 | + git commit -S -m "Your detailed commit message" |
| 90 | + ``` |
| 91 | + |
| 92 | + For more on signing commits, see [GitHub's guide on signing commits](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits). |
| 93 | + |
| 94 | +### Submitting Pull Requests |
| 95 | + |
| 96 | +Once you've followed the above steps and are satisfied with your changes: |
| 97 | + |
| 98 | +1. Push your changes to your forked repository. |
| 99 | +2. Go to the original Model API repository you forked and click "New pull request". |
| 100 | +3. Choose your fork and the branch with your changes to open a pull request. |
| 101 | +4. Fill in the pull request template with the necessary details about your changes. |
| 102 | + |
| 103 | +We look forward to your contributions! |
| 104 | + |
| 105 | +## License |
| 106 | + |
| 107 | +You accept that your contributions will be licensed under the [Apache-2.0 License](https://choosealicense.com/licenses/apache-2.0/) if you contribute to this repository. If this is a concern, please notify the maintainers. |
0 commit comments