Thank you for your interest in contributing. External contributors should do all
development in a personal fork and submit changes to
NVIDIA/TensorRT-Model-Connect
through a pull request. Do not work directly on the upstream main branch.
The Contributor Quickstart and architecture guide provide project-specific design, testing, and ownership guidance.
Maintainers can optionally request an advisory documentation review. It is manually triggered, keeps reports private, and does not replace the existing merge gates.
Use GitHub's Fork button to create
https://github.com/YOUR-GITHUB-USERNAME/TensorRT-Model-Connect, then clone
your fork and add the NVIDIA repository as upstream:
git clone https://github.com/YOUR-GITHUB-USERNAME/TensorRT-Model-Connect.git
cd TensorRT-Model-Connect
git remote add upstream https://github.com/NVIDIA/TensorRT-Model-Connect.git
git fetch upstreamIn this layout, origin is your writable fork and upstream is the canonical
repository. Keep these roles separate.
Create a short-lived topic branch for each contribution. Do not develop on your
fork's main, because it may be behind upstream:
git switch -c docs/improve-contributing upstream/mainUse a concise branch name that describes one purpose, such as
fix/qwen-tokenizer or docs/model-validation.
Before editing, identify the component that owns the behavior. A normal model
contribution changes only families/<owner>/**. It may duplicate sibling
implementation but must not import it. A shared-core change requires a concrete
model-independent contract that the current public API cannot express.
Start with the relevant guide:
- Add a Model Family
- AI-Native Horizontal Scaling Architecture
- Bring Your Own Kernel, only for an explicit BYOK contribution
Python family builders are plain functions and must not inherit. Do not add a compatibility path, fallback, migration layer, family dependency hash, or artifact digest. Digest pins are limited to CI container base images.
Open an issue before investing in a large, cross-cutting, or user-visible design when the intended ownership or approach is not already clear.
Keep each pull request focused on one problem. Add or update focused tests when behavior changes, and update documentation when users or developers will observe the change.
Install the lightweight commit-time quality hooks once in each clone:
python3 -m pip install --requirement requirements/community-ci.txt
pre-commit install --install-hooksOn Windows, use py -3 -m pip in place of python3 -m pip.
The hooks trim trailing whitespace, ensure one final newline, validate YAML, check Ruff, and verify clang-format. Pre-commit manages the Ruff and clang-format environments on Linux, macOS, and Windows. There is no pre-push hook: builds and the broader source-only CPU suite run automatically on the pull request after the branch is pushed.
Start with repository consistency checks:
PYTHONPATH=core/builder:apps/benchmark:. python3 -m tools.model_ci validate
PYTHONPATH=core/builder:apps/benchmark:. python3 tools/test_impact.py --validate
git diff --checkThen run the smallest meaningful tests for the code you changed. Model work also needs the declared model, runtime, hardware, and comparison evidence. For documentation changes, run:
npm --prefix website ci
npm --prefix website run test:model-support
npm --prefix website run buildDo not weaken a test, oracle, or acceptance threshold to make a change pass. If you believe a test is incorrect, explain the evidence in the pull request and ask a maintainer to review it.
Repository history uses short, imperative, Conventional Commit-style subjects, for example:
docs(contributing): clarify external workflow
fix(qwen): preserve tokenizer contract
test(ci): cover fork pull requests
Sign off every commit as described in Signing Your Work:
git commit --signoff -m "docs(contributing): clarify external workflow"Before opening the pull request, incorporate the current upstream main and
rerun the affected checks:
git fetch upstream
git rebase upstream/main
git push --set-upstream origin docs/improve-contributingIf you rebase a branch that you already pushed, never use an unguarded force
push. Use git push --force-with-lease, and coordinate before rewriting a
branch that other people are using.
Open the pull request from your fork branch to
NVIDIA/TensorRT-Model-Connect:main and keep it in draft while completing the
self-review below. Complete every section of the pull-request template; use
Not applicable: <reason> instead of deleting a section. Include:
- Background: the problem, motivation, current behavior, and linked issue;
- Exit Criteria: the conditions that define completion, including important non-goals;
- Implementation: the approach, affected models and components, and any API, ABI, bundle, dependency, compatibility, migration, or rollout changes;
- Validation: exact commands and results, tested head and dependency/model revisions, environment and hardware, plus paths that were not run; and
- Contributor Self-Review: confirmation that you reviewed your change; and
- Notes For Future Readers: remaining risk, compatibility or rollout notes, third-party provenance, and useful follow-up context.
Once the pull request is marked ready, PR Metadata / Required checks that
these sections and the structured validation evidence are present, including
the contributor self-review confirmation. The trusted triage workflow derives
model and component labels from the actual diff and repository ownership
metadata; it uses the template only for declared risk and compatibility-change
labels. DCO sign-off is enforced by the repository's DCO check rather than a
self-attested template checkbox.
Compilation, unit tests, inference, model parity, target-hardware execution, performance, and release qualification are separate evidence levels. Claim only what the recorded validation proves.
Review the exact current draft pull-request head after implementation and local validation. Codex users can run the repository-provided skill from the repository root:
$review-trtmc-pr review this draft PR as a contributor self-review. Do not
publish comments or change the branch. Report architecture, correctness, and
validation findings first.
For an earlier pass before a draft PR exists, run:
$review-trtmc-pr self-review my current branch and working tree against
upstream/main. Do not modify files.
Use /skills or type $ to confirm that the skill is available. If it does
not appear, restart Codex from the repository root.
Using Codex is recommended, not required. A manual review or another review tool is also acceptable. When the review is complete, select the single Contributor Self-Review checkbox in the pull-request description.
Resolve blocking and high-severity findings before marking the pull request ready. If a finding requires an architecture or policy decision, leave the pull request in draft, record the question, and ask a maintainer. Rerun the affected validation and self-review after material changes. Self-review does not replace public CI, protected CI, or maintainer review.
Opening a pull request or pushing a new commit automatically starts Stable
Community CI with the existing four parallel CPU stages: source quality,
documentation, ownership and impact, and C++/Python unit tests. The
Community CPU / Required result requires all four to pass.
Stable automatic Community GPU execution remains disabled during qualification.
Maintainers retain the existing manual GPU smoke option. Dev Community CI
is the experimental pipeline from the protected CI development branch. When
TRTMC_COMMUNITY_CI_DUAL_RUN=true, it tests the same captured PR snapshot.
Only after Community CPU / Required passes in Dev does Dev start the Brev GPU
stage for GPU-impacting changes. Dev failures do not change Stable's result.
The CPU jobs run on fresh GitHub-hosted ubuntu-24.04 runners with read-only
repository permission and no access to private runners, secrets, or GPUs.
Source quality checks required SPDX headers and rejects changes to LICENSE
or NOTICE relative to the tested merge's base.
The Dev GPU experiment
is maintained separately on ci/developer. Its isolated GPU instance receives no
repository, Hub, or Brev credentials. Stable retains its existing manual GPU
configuration, including the Hub credential for gated checkpoints; this PR does
not change that configuration.
Public Actions logs show the individual stages and failing commands. The Community CI guide explains the switch, CI branch selection, qualification evidence, and later promotion. Native pull-request checks such as DCO and PR Metadata remain separate. The existing Internal CI trigger and merge gate continue unchanged during this comparison.
Internal premerge remains the required gate during Community premerge qualification. Follow the existing maintainer-triggered process below until the separate gate migration is complete.
Opening a pull request or pushing to your fork does not start the protected premerge suite. After public CPU validation passes and the pull request is ready for protected CI, mention the repository maintainer in a pull-request comment:
@yifeif-nv This PR is ready for CI. Please trigger CI for the current head.
The maintainer verifies the pull-request head and a successful Community CPU / Required stage in the existing PR run, then applies the one-shot run-internal-ci
label. Only
collaborators with repository maintain or admin permission can authorize
that trigger.
The trusted bridge consumes the label, rechecks that CPU aggregate in Community
CI, captures the current PR head SHA, and dispatches protected premerge
validation without waiting for the later GPU stage.
If authorization rejects the request, ask the maintainer to remove and re-add
the retained label after satisfying the reported prerequisite. Adding an
already-present label does not create a new trigger event.
Wait for TRTMC Internal CI / Automated premerge gate to pass on the exact
pull-request head SHA. This is an automated test result, not a request for an
individual maintainer review.
If you push another commit, the previous result no longer validates the current
head; finish the update, wait for the automatic Community CPU stage, and
mention @yifeif-nv once to request a new protected run. Private runner details,
logs, artifacts, and URLs are not part of the public contribution interface.
Address review feedback on the same topic branch and sign off every new commit. Keep the pull request current with upstream when requested. A new head requires a fresh public merge result and a fresh maintainer-triggered protected result before the pull request can merge. Maintainers merge accepted changes according to the repository ruleset.
The repository's development history consistently favors these practices:
- keep commits and pull requests single-purpose and easy to review;
- use an imperative Conventional Commit-style subject with a useful scope;
- keep model-owned behavior and its tests close to the model owner;
- pair behavior changes with focused regression coverage;
- record exact commands, revisions, artifacts, hardware, and untested paths;
- preserve copyright, license, attribution, and third-party provenance; and
- treat CI success as evidence for the exact tested revision, not for later commits or unexecuted configurations.
Contributions accepted into this project are licensed under the Apache License 2.0 unless explicitly stated otherwise.
Preserve all existing copyright, license, and attribution notices. If a contribution incorporates or is derived from third-party material, identify its source, version, and license in the pull request and include any notices required for redistribution. Do not submit material unless you have the right to do so under a license compatible with this project.
The DCO sign-off requirement is enforced prospectively for commits introduced by pull requests and protected-branch updates after its adoption. Existing Git history is not rewritten.
-
We require all contributors to sign off their commits. This certifies that the contribution is your original work, that you have the right to submit it under the same license, or that it uses a compatible license.
- Contributions containing commits without a
Signed-off-byline are not accepted.
- Contributions containing commits without a
-
To sign off a commit, use the
--signoff(or-s) option:git commit --signoff -m "docs(contributing): clarify external workflow"This appends a line like this to the commit message:
Signed-off-by: Your Name <your@email.com> -
The full text of the Developer Certificate of Origin follows:
Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.