Contributing¶

AMD values and encourages community contributions to IRON / MLIR-AIE — bug reports, questions, docs, and code are all welcome. Please review the guidance below before contributing.

Development workflow¶

We use GitHub to host code, collaborate, and manage version control. All changes go through pull requests; GitHub issues track known bugs, and GitHub Discussions are the place for usage questions and feature ideas. For more informal, real-time chat with the team and other users, join the ROCm Discord and look for the ROCm-NPU channel.

Issue tracking¶

Before filing a new issue, search the existing issues to make sure it isn't already listed.

If your issue already exists, add a comment with any extra detail (such as how you reproduced it) rather than opening a duplicate.
If you're not sure whether it's the same, err on the side of filing and link the similar issue by number — we'll close duplicates if they turn out to match.
Otherwise, open a new issue with the bug-report or feature-request template. Include as much detail as you can — what you ran, what you expected, what happened, and your environment (device, OS, IRON version) — so we can reproduce it quickly. Check back on the issue, since we may need more information.

Pull requests¶

Fork the repo and create a branch off main — the default integration branch.
Set up the dev environment so the formatting and lint hooks are in place:
```
source utils/env_install.sh --dev
```
This installs the toolchain and registers the pre-commit / pre-push hooks (see Formatting and hooks below). To build the toolchain from source instead of installing wheels, see Building from source.
Make your change, targeting main. Keep the PR focused, and make sure it builds.
Add tests for new functionality. New features should come with a test or example so we can confirm they work and stay working. Don't break existing tests.
Open the PR using the pull request template. Fill in the description and checklist, and link the related issue with Fixes #123.
Get CI green and work with your reviewer. CI runs builds, tests, linting, and type checks. A maintainer reviews once it passes; push follow-up commits to the same branch to address feedback. We'll let you know once your change is merged.

Small, self-contained PRs with a clear description are the easiest to review and the fastest to merge.

By creating a PR, you agree that your contribution will be licensed under the terms of the LICENSE file in the root of this repository.

New feature development¶

For larger features, start a Discussion before writing code — maintainers are happy to give direction and feedback early. Any new feature or API should also come with the corresponding documentation update (this repository holds its own docs; there is no separate docs repo).

Formatting and hooks¶

Formatting and linting are enforced by pre-commit, installed by utils/env_install.sh --dev. The hooks run automatically — lightweight validators (REUSE, merge-conflict markers, etc.) on every commit, and the heavier formatting/lint checks (clang-format, black, ruff check) on git push — so CI should never be the first place you find out about a formatting or lint issue. To run them by hand:

pre-commit run --all-files

The hooks cover:

C++ — clang-format (LLVM style; config in .clang-format).
Python and notebooks — black for formatting, plus nbstripout to scrub notebook output before it is committed.
Python lint — ruff check (see Linting Python below).
Baseline hygiene — trailing whitespace, end-of-file, merge-conflict markers, and REUSE license-header compliance.

If you would rather not install the hooks, you can run clang-format -i <file>, black <file>, and ruff check --fix <file> directly, but the hooks are the supported path.

Linting Python¶

Python style and common bugs are checked with ruff, scoped to python/{iron,utils,helpers, compiler} and a growing set of programming_examples/ directories — ruff.toml's include list at the repo root is the source of truth for exactly which paths are covered. The pre-push hook runs ruff check and blocks the push on any violation; run it by hand with:

ruff check

Rules enabled: pyflakes/pycodestyle errors (E, F), import sorting (I), a narrow pep8-naming subset (N802, N816), and pydocstyle (D, Google convention, python/{iron,utils,helpers,compiler} only for now) for docstring style — see Documenting your code. ruff.toml documents, rule by rule, why anything is excluded from the default rule set; per-file exceptions live in [lint.per-file-ignores], each with an inline justification. Follow that pattern if you need a new one — an unexplained exception won't pass review.

Type checking Python¶

The pure-Python package (python/{iron,utils,helpers,compiler}) and a growing set of programming_examples/ directories (pyrightconfig.json's include list at the repo root is the source of truth) are type-checked with pyright in standard mode, and CI fails on any error. After a normal build/install you can run:

pyright

When a diagnostic points at a symbol that genuinely exists at runtime but comes from a compiled extension (aie._mlir_libs) or a tablegen-generated op/enum wildcard (from aie.dialects... import *), suppress just that line, naming the exact rule:

with Context() as ctx:  # pyright: ignore[reportUndefinedVariable]

Reserve suppressions for these binding gaps. Fix real type issues at the source (add a None guard or raise, tighten an annotation, initialize before a branch) rather than silencing them. Do not add blanket file-level ignores or disable rules.

Documenting your code¶

Python — document public functions, classes, and modules with docstrings, using the Google convention (Args:/Returns:/Raises: sections, one arg per line as name (type[, optional]): description). These are rendered into the API reference via mkdocstrings, so a good docstring is also good published documentation. In python/{iron,utils,helpers,compiler}, ruff's pydocstyle rules enforce the style of a docstring once you've written one (blank-line placement, imperative first line, terminal punctuation) — see Linting Python. Writing a docstring in the first place is still expected for anything public-facing, just not yet machine-enforced.
C++ — use Doxygen-style triple-slash comments (///, with \brief, \param, \returns as needed) on public declarations in headers. These feed the C++ API reference.

Governance¶

IRON / MLIR-AIE is led and managed by AMD, and we welcome community contributions. Maintainers (listed in the repository's CODEOWNERS file) review all proposed changes and can merge to the repository. Everyone else is a contributor — file issues, improve docs, submit PRs for contained changes, and propose larger features in Discussions.

By contributing, you agree that your contributions will be licensed under the LICENSE file in the root of this source tree. Every file must carry an SPDX license header; the REUSE hook checks this on push.