|
| 1 | +# Contributing to ONNX IR |
| 2 | + |
| 3 | +Welcome to the ONNX IR project! We appreciate your interest in contributing. |
| 4 | + |
| 5 | +## Code Style and Design Principles |
| 6 | + |
| 7 | +Before contributing, please familiarize yourself with our development guidelines: |
| 8 | + |
| 9 | +- **[Coding Style](https://github.com/onnx/ir-py/wiki/Coding-style)**: Our coding conventions and style guidelines |
| 10 | +- **[Design Principles](https://github.com/onnx/ir-py/wiki/Design-Principles)**: The core principles guiding the design of ONNX IR |
| 11 | + |
| 12 | +## Development Environment Setup |
| 13 | + |
| 14 | +### Prerequisites |
| 15 | + |
| 16 | +- Python 3.9 or higher |
| 17 | +- Git |
| 18 | + |
| 19 | +### Setting up the Development Environment |
| 20 | + |
| 21 | +1. **Clone the repository**: |
| 22 | + ```bash |
| 23 | + git clone https://github.com/onnx/ir-py.git |
| 24 | + cd ir-py |
| 25 | + ``` |
| 26 | + |
| 27 | +2. **Create a virtual environment** (recommended): |
| 28 | + ```bash |
| 29 | + python -m venv venv |
| 30 | + source venv/bin/activate # On Windows: venv\Scripts\activate |
| 31 | + ``` |
| 32 | + |
| 33 | +3. **Install development dependencies**: |
| 34 | + ```bash |
| 35 | + pip install -r requirements-dev.txt |
| 36 | + ``` |
| 37 | + |
| 38 | +4. **Install the package in development mode**: |
| 39 | + ```bash |
| 40 | + pip install -e . |
| 41 | + ``` |
| 42 | + |
| 43 | +## Code Quality and Linting |
| 44 | + |
| 45 | +We use [lintrunner](https://github.com/suo/lintrunner) for code quality checks. The project includes several linters: |
| 46 | + |
| 47 | +- **RUFF**: Python linter and code formatter |
| 48 | +- **MYPY**: Static type checker |
| 49 | +- **EDITORCONFIG-CHECKER**: EditorConfig compliance checker |
| 50 | + |
| 51 | +### Setting up lintrunner |
| 52 | + |
| 53 | +1. **Initialize lintrunner** (this installs the required linting tools): |
| 54 | + ```bash |
| 55 | + lintrunner init |
| 56 | + ``` |
| 57 | + |
| 58 | +2. **Run all linters**: |
| 59 | + ```bash |
| 60 | + lintrunner |
| 61 | + ``` |
| 62 | + |
| 63 | +3. **Apply automatic fixes** where possible: |
| 64 | + ```bash |
| 65 | + lintrunner -a --output oneline |
| 66 | + ``` |
| 67 | + |
| 68 | +4. **Format code only**: |
| 69 | + ```bash |
| 70 | + lintrunner f --output oneline |
| 71 | + ``` |
| 72 | + |
| 73 | +### Linting specific files |
| 74 | + |
| 75 | +You can lint specific files or directories: |
| 76 | +```bash |
| 77 | +lintrunner src/onnx_ir/ |
| 78 | +lintrunner path/to/specific/file.py |
| 79 | +``` |
| 80 | + |
| 81 | +## Testing |
| 82 | + |
| 83 | +The project uses [nox](https://nox.thea.codes/) for testing across different environments and [pytest](https://pytest.org/) as the test runner. |
| 84 | + |
| 85 | +### Running tests with nox |
| 86 | + |
| 87 | +```bash |
| 88 | +# Run all tests |
| 89 | +nox -s test |
| 90 | + |
| 91 | +# Run tests with specific Python version (if available) |
| 92 | +nox -s test --python 3.11 |
| 93 | + |
| 94 | +# Run tests with ONNX weekly build |
| 95 | +nox -s test-onnx-weekly |
| 96 | + |
| 97 | +# Run tests with PyTorch nightly |
| 98 | +nox -s test-torch-nightly |
| 99 | +``` |
| 100 | + |
| 101 | +### Running tests directly with pytest |
| 102 | + |
| 103 | +If you prefer to run tests directly: |
| 104 | + |
| 105 | +```bash |
| 106 | +# Run all tests |
| 107 | +pytest |
| 108 | + |
| 109 | +# Run tests with coverage |
| 110 | +pytest --cov=onnx_ir |
| 111 | + |
| 112 | +# Run specific test file |
| 113 | +pytest tests/test_specific.py |
| 114 | + |
| 115 | +# Run doctests |
| 116 | +pytest src --doctest-modules |
| 117 | +``` |
| 118 | + |
| 119 | +## Submitting Contributions |
| 120 | + |
| 121 | +### Before submitting |
| 122 | + |
| 123 | +1. **Ensure your code passes all linting checks**: |
| 124 | + ```bash |
| 125 | + lintrunner |
| 126 | + ``` |
| 127 | + |
| 128 | +2. **Run the test suite**: |
| 129 | + ```bash |
| 130 | + pytest path/to/test.py |
| 131 | + ``` |
| 132 | + |
| 133 | +### Pull Request Guidelines |
| 134 | + |
| 135 | +1. **Fork the repository** and create a feature branch from `main` |
| 136 | +2. **Write clear, descriptive commit messages** |
| 137 | +3. **Add tests** for new functionality |
| 138 | +4. **Update documentation** if needed |
| 139 | +5. **Ensure all CI checks pass** |
| 140 | +6. **Request review** from maintainers |
| 141 | + |
| 142 | +### Pull Request Description |
| 143 | + |
| 144 | +Use clear and descriptive PR description: |
| 145 | +``` |
| 146 | +[component] brief description of change |
| 147 | +
|
| 148 | +More detailed explanation if needed, including: |
| 149 | +- What was changed |
| 150 | +- Why it was changed |
| 151 | +- Any breaking changes |
| 152 | +``` |
| 153 | + |
| 154 | +## Development Workflow |
| 155 | + |
| 156 | +1. **Create an issue** or comment on an existing one to discuss your proposed changes |
| 157 | +2. **Fork the repository** and create a feature branch |
| 158 | +3. **Make your changes** following our coding style and design principles |
| 159 | +4. **Add or update tests** as appropriate |
| 160 | +5. **Run linting and tests** locally |
| 161 | +6. **Submit a pull request** with a clear description of your changes |
| 162 | + |
| 163 | +## Getting Help |
| 164 | + |
| 165 | +- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/onnx/ir-py/issues) |
| 166 | +- **Discussions**: For questions and discussions, use [GitHub Discussions](https://github.com/onnx/ir-py/discussions) |
| 167 | +- **Documentation**: Visit the [official documentation](https://onnx.ai/ir-py/) |
| 168 | + |
| 169 | +## License |
| 170 | + |
| 171 | +By contributing to ONNX IR, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE). |
| 172 | + |
| 173 | +Thank you for contributing to ONNX IR! 🎉 |
0 commit comments