You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Guidelines for writing production code. Key values: simplicity, minimalism, and
4
-
elegance.
3
+
Guidelines for production code in ModelOpt. Key values: simplicity, minimalism,
4
+
and elegance.
5
5
6
-
## Philosophy
6
+
## Principles
7
7
8
-
-**Be Surgical, Minimal edits.** Touch only what the task requires. No speculative
9
-
refactors, drive-by cleanup, or half-finished implementations.
10
-
-**Good design simplifies code.** Good architecture makes code easier to read
11
-
and easier to change. Use abstractions that put code at the right level, and
12
-
keep designs extensible for known needs without over-engineering for
13
-
speculative future cases. Heavy branching and conditional logic are design
14
-
smells because they are hard to read and prone to bugs.
8
+
-**Design for simplicity.** Before planning non-trivial changes, choose the
9
+
design that keeps code easiest to read and change. Put behavior at the right
10
+
level, tie extensibility to known needs, and treat heavy branching or
11
+
conditional logic as bad design smells.
12
+
-**Be surgical.** Touch the code required to solve the actual problem, whether
13
+
that is one line or a broader design change. Avoid speculative refactors,
14
+
drive-by cleanup, unrelated rewrites, and half-finished implementations.
15
+
-**Fix root causes.** Prefer the right fix over the most local patch. Do not
16
+
paper over symptoms with temporary fixes unless the temporary nature and
17
+
follow-up are explicit.
15
18
-**Respect ownership and layering.** Keep behavior in the layer that owns it.
16
19
Parent abstractions should contain shared contracts and shared behavior, not
17
20
child-specific special cases.
18
-
-**Prefer clean extension over branching.** When behavior varies, use explicit
19
-
extension points such as strategies, adapters, callbacks, or overrides. Update
20
-
a parent or shared base when it is the right extension point, but do not add
21
-
extension points for speculative future cases.
22
-
-**Use helpers for duplication and right-level abstraction.** Add helpers when
23
-
they remove duplicated code across multiple places or let higher-level code
24
-
use helpful names while low-level details stay abstracted away.
25
-
-**Use meaningful names.** Methods, variables, objects, and helpers should make
26
-
intent clear at the point of use.
27
-
-**Code should read like prose.** Well-written code is self-explanatory and
28
-
elegant. Keep high-level orchestration clear, and move low-level mechanics
29
-
into well-named helpers when that improves readability.
30
-
-**Critical code first.** Order files so the most important or user-facing code
31
-
appears before helper details when local conventions allow it.
32
-
-**Validate at boundaries, then trust invariants.** Check untrusted inputs at system boundaries such as user input, external APIs, files, networks, and process boundaries. After validation, internal code should trust its types and invariants instead of adding defensive checks for states that should be impossible.
33
-
-**Comments explain why.** Code is the source of truth for what happens and
21
+
-**Use abstractions to simplify.** Add helpers, base classes, registries,
22
+
adapters, plugins, or other abstractions when they remove real duplication,
23
+
clarify ownership, or put behavior at the right level. Do not add abstractions
24
+
for speculative future cases.
25
+
-**Prefer extension over branching.** When behavior varies, use explicit
26
+
extension points such as adapters, registries, callbacks, plugins, or
27
+
overrides. Update a parent or shared base when it is the right extension
28
+
point. Do not add extension points for speculative future cases.
29
+
-**Make code readable at the point of use.** Names, types, and structure should
30
+
make intent clear. Keep high-level orchestration clear, and move low-level
31
+
mechanics into well-named helpers when that improves readability.
32
+
-**Put critical code first.** Order files so the most important or user-facing
33
+
code appears before helper details when local conventions allow it.
34
+
-**Validate outside input once.** Check user input, files, network responses,
35
+
and external API results at the edge. Keep internal code simple instead of
36
+
repeatedly checking for impossible states.
37
+
-**Comments explain why, concisely.** Code is the source of truth for what happens and
34
38
how. Add comments only when the reason is not obvious. Redundant comments are
35
39
a maintainability burden. If a comment feels necessary, first check whether
36
40
better design or naming would make the code explain itself.
37
-
-**Preserve existing comments.** Minimalism applies to new comments; do not
38
-
delete existing comments casually. Production code is shared by many
39
-
developers, and unnecessary changes to others' code create avoidable review and
40
-
approval overhead.
41
-
-**Docstrings scale with API level.** Higher-level and user-visible APIs
42
-
deserve useful docstrings, including examples when helpful. Lower-level
43
-
internals should use minimal docstrings, or none, when well-named identifiers
44
-
are enough.
45
-
-**Remove dead code.** Delete unused imports, unreachable branches, and
46
-
obsolete placeholders.
47
-
-**Use workspace-relative paths** in commands and file references unless an
48
-
absolute path is needed to disambiguate.
41
+
-**Apply comment guidance to new comments only.** Use these standards only when adding
42
+
new comments. Do not rewrite or delete existing comments as cleanup;
43
+
-**Scale documentation to the API.** Higher-level and user-visible APIs deserve
44
+
useful docstrings, including examples when helpful. Lower-level internals need
45
+
docstrings only when names, types, and structure are not enough.
46
+
-**Remove dead code.** Delete unused imports, unreachable branches, obsolete
47
+
placeholders, stale TODOs, and debug code when they are part of the touched
48
+
behavior.
49
+
-**Use workspace-relative paths.** Use relative paths in commands and file
50
+
references unless an absolute path is needed to disambiguate.
49
51
50
52
## Testing
51
53
@@ -62,10 +64,19 @@ elegance.
62
64
63
65
-**Avoid stray CPU-GPU syncs.** Tensor metadata such as `tensor.shape` is safe
64
66
to read, but scalar extraction or CPU transfers such as `tensor.item()`,
65
-
`float(tensor)`, `bool(tensor)`, `tensor.cpu()`, and `tensor.numpy()` can force
66
-
CPU-GPU synchronization. Keep computation on GPU unless the CPU actually needs
67
-
the value.
67
+
`float(tensor)`, `bool(tensor)`, `tensor.cpu()`, `tensor.numpy()`, etc. can
68
+
force CPU-GPU synchronization. Keep computation on GPU unless the CPU actually
69
+
needs the value.
68
70
-**Use rank-aware logging.** Default to `print_rank_0` instead of `print` and
69
71
`warn_rank_0` instead of generic warnings. Use per-rank output only when each
70
72
process needs to report distinct state. Generic prints and warnings clog
71
73
distributed logs.
74
+
-**Respect distributed invariants.** Avoid hidden synchronization, global state,
75
+
per-rank file races, or assumptions that only hold on a single process.
76
+
77
+
## Compatibility
78
+
79
+
-**Preserve config and checkpoint compatibility.** Treat ModelOpt config schemas
80
+
and checkpoint formats as persisted contracts. When changing configs such as
81
+
`QuantizeConfig`, maintain backward compatibility with previous ModelOpt
82
+
checkpoints unless a breaking change is explicit and intentionally handled.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+12-2Lines changed: 12 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -79,7 +79,7 @@ If you are an external contributor, seek guidance from `@NVIDIA/modelopt-setup-c
79
79
80
80
See [`modelopt/torch/quantization/utils/calib_utils.py`](./modelopt/torch/quantization/utils/calib_utils.py) for an example of the correct license header format.
81
81
82
-
## 📝 Writing tests
82
+
## 📝 Writing and running tests
83
83
84
84
We use [pytest](https://docs.pytest.org/) for all tests. For any new features / examples, make sure to add tests and that the coverage check in your PR passes. The tests are organized into the following directories:
85
85
@@ -89,7 +89,17 @@ We use [pytest](https://docs.pytest.org/) for all tests. For any new features /
89
89
-`tests/gpu_trtllm`: Fast GPU-based unit tests for the core ModelOpt library for TensorRT-LLM features. In most cases, they should not take more than a few seconds to run.
90
90
-`tests/examples`: Integration tests for ModelOpt examples. They should not take more than a few minutes to run. Please refer to [example test README](./tests/examples/README.md) for more details.
91
91
92
-
Please refer to [noxfile.py](./noxfile.py) for more details on how to run the tests and their dependencies.
92
+
For focused local validation, run `pytest` directly on the relevant test path. For example:
93
+
94
+
```bash
95
+
pytest tests/unit/torch/quantization
96
+
```
97
+
98
+
For standard repo sessions and dependency setup, use [noxfile.py](./noxfile.py). Run `nox -l` to list available sessions, then run the matching session with `nox -s <session>`. For example, `partial_unit` covers the broader torch unit test suite, including areas such as quantization:
0 commit comments