Skip to content

Commit 98b1108

Browse files
kaix-nvdanielkorzekwa
authored andcommitted
Add contribution guidelines for experimental features (#867)
## What does this PR do? **Type of change:** ? <!-- Use one of the following: Bug fix, new feature, new example, new tests, documentation. --> **Overview:** ? ## Usage <!-- You can potentially add a usage example below. --> ```python # Add a code snippet demonstrating how to use this ``` ## Testing <!-- Mention how have you tested your change if applicable. --> ## Before your PR is "*Ready for review*" <!-- If you haven't finished some of the above items you can still open `Draft` PR. --> - **Make sure you read and follow [Contributor guidelines](https://github.com/NVIDIA/Model-Optimizer/blob/main/CONTRIBUTING.md)** and your commits are signed. - **Is this change backward compatible?**: Yes/No <!--- If No, explain why. --> - **Did you write any new necessary tests?**: Yes/No - **Did you add or update any necessary documentation?**: Yes/No - **Did you update [Changelog](https://github.com/NVIDIA/Model-Optimizer/blob/main/CHANGELOG.rst)?**: Yes/No <!--- Only for new features, API changes, critical bug fixes or bw breaking changes. --> ## Additional Information <!-- E.g. related issue. --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive guide for experimental optimization technique development, including recommended structure, testing conventions, licensing requirements, and graduation path to production. * **New Features** * Introduced experimental package with templates and utilities for implementing research-stage optimization techniques. Includes configuration framework and example code patterns. Emits stability warnings to indicate unstable APIs. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Signed-off-by: Kai Xu <kaix@nvidia.com>
1 parent 35d0f52 commit 98b1108

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

experimental/README.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Experimental Optimization Techniques
2+
3+
Experimental optimization algorithms and research prototypes under active development.
4+
5+
## Purpose
6+
7+
For new optimization techniques (quantization, pruning, sparsity, etc.) that are:
8+
9+
- Novel or research-stage algorithms
10+
- Not yet production-ready
11+
- May have unstable APIs
12+
13+
**⚠️ Warning**: Experimental features are not guaranteed to work across releases. APIs may change or features may be removed without notice. Use at your own risk.
14+
15+
## Requirements
16+
17+
Each experimental technique must include:
18+
19+
- **README.md** - Explains what the technique does, how to use it, current status, model support, and references
20+
- **Working code** - Clear, readable implementation
21+
- **Comprehensive tests** - Good test coverage demonstrating correctness
22+
- **Detailed documentation** - Clear docs on usage, APIs, and behavior
23+
- **Example** - Demonstrating usage
24+
- **Model support list** - Which models/frameworks are supported
25+
- **Deployment info** - Supported deployment frameworks (TensorRT-LLM, vLLM, SGLang, etc.) and whether custom kernels are required
26+
- **requirements.txt** - Additional dependencies beyond base modelopt
27+
- **License headers** - Apache 2.0 headers on all Python files
28+
29+
## Example Structures
30+
31+
Organize your code however makes sense. Here are some examples:
32+
33+
**Simple flat structure:**
34+
35+
```text
36+
experimental/my_technique/
37+
├── README.md
38+
├── requirements.txt
39+
├── my_technique.py
40+
├── test_my_technique.py
41+
└── example.py
42+
```
43+
44+
**Package structure:**
45+
46+
```text
47+
experimental/my_technique/
48+
├── README.md
49+
├── requirements.txt
50+
├── my_technique/
51+
│ ├── __init__.py
52+
│ ├── core.py
53+
│ └── config.py
54+
├── tests/
55+
│ └── test_core.py
56+
└── examples/
57+
└── example_usage.py
58+
```
59+
60+
## Quality Standards
61+
62+
Experimental code must meet quality standards:
63+
64+
- Comprehensive test coverage required
65+
- Clear documentation required
66+
- Pass all pre-commit checks
67+
68+
## PR Guidelines
69+
70+
Keep PRs focused and reviewable:
71+
72+
- **Split large features**: Break complex techniques into multiple PRs if needed
73+
- **Reasonable scope**: PRs with tens of thousands of lines are difficult to review
74+
- **Incremental development**: Consider submitting core functionality first, then enhancements
75+
- If your technique is large, discuss the implementation plan in an issue first
76+
77+
## Example Documentation Template
78+
79+
Your technique's README.md should include:
80+
81+
```markdown
82+
# Your Technique Name
83+
84+
Brief description of the optimization technique.
85+
86+
## Model Support
87+
88+
| Model/Framework | Supported | Notes |
89+
|-----------------|-----------|-------|
90+
| LLMs (Llama, GPT, etc.) || Tested on Llama 3.1 |
91+
| Diffusion Models || Not yet supported |
92+
| Vision Models || Experimental |
93+
94+
## Deployment
95+
96+
| Framework | Supported | Notes |
97+
|-----------|-----------|-------|
98+
| TensorRT-LLM || Requires custom kernel |
99+
| vLLM || Not yet supported |
100+
| SGLang || Uses standard ops |
101+
102+
## Usage
103+
104+
\`\`\`python
105+
from experimental.my_technique import my_optimize
106+
...
107+
\`\`\`
108+
109+
## Status
110+
111+
Current state: Prototype
112+
113+
Known issues:
114+
- Issue 1
115+
- Issue 2
116+
117+
## References
118+
119+
- [Paper](link)
120+
- [Code repository](link)
121+
- [Project page](link)
122+
- [Related work](link)
123+
```
124+
125+
## Path to Production
126+
127+
When a technique is ready for production (proven effective, stable API, full tests, comprehensive docs), it can be promoted to the main `modelopt` package.
128+
129+
**Contributors**: Open an issue proposing graduation with evidence of effectiveness and stability.
130+
131+
**Users**: If you find an experimental feature valuable, open a GitHub issue requesting promotion to production. User demand is a key signal for production readiness.
132+
133+
## Questions?
134+
135+
Open a GitHub issue with `[experimental]` prefix.

experimental/__init__.py

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
"""Experimental optimization techniques for Model Optimizer.
17+
18+
This package contains experimental and research-stage optimization algorithms
19+
that are under active development. APIs may change without notice.
20+
21+
Warning:
22+
Code in this package is experimental and not covered by semantic versioning.
23+
Use at your own risk in production environments.
24+
"""
25+
26+
import warnings
27+
28+
warnings.warn(
29+
"The 'experimental' package contains unstable APIs that may change. "
30+
"Use at your own risk in production environments.",
31+
FutureWarning,
32+
stacklevel=2,
33+
)
34+
35+
__all__ = []

0 commit comments

Comments
 (0)