HEIR – Development

Docs: AI Tool Use Policy

Mon, 01 Jan 0001 00:00:00 +0000

Nb., this policy was adapted from the LLVM AI Tool Use Policy.

Policy

This project’s policy is that contributors can use whatever tools they would like to craft their contributions, but there must be a human in the loop. Contributors must read and review all LLM-generated code or text before they ask other project members to review it. The contributor is always the author and is fully accountable for their contributions. Contributors should be sufficiently confident that the contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be able to answer questions about their work during review.

We expect that new contributors will be less confident in their contributions, and our guidance to them is to start with small contributions that they can fully understand to build confidence. We aspire to be a welcoming community that helps new contributors grow their expertise, but learning involves taking small steps, getting feedback, and iterating. Passing maintainer feedback to an LLM doesn’t help anyone grow, and does not sustain our community.

Contributors are expected to be transparent and label contributions that contain substantial amounts of tool-generated content. Our policy on labelling is intended to facilitate reviews, and not to track which parts of the project are generated. Contributors should note tool usage in their pull request description, commit message, or wherever authorship is normally indicated for the work. For instance, use a commit message trailer like Assisted-by: <name of code assistant>. This transparency helps the community develop best practices and understand the role of these new tools.

This policy includes, but is not limited to, the following kinds of contributions:

Code, usually in the form of a pull request
RFCs or design proposals
Issues or security vulnerabilities
Comments and feedback on pull requests

Details

To ensure sufficient self review and understanding of the work, it is strongly recommended that contributors write PR descriptions themselves (if needed, using tools for translation or copy-editing). The description should explain the motivation, implementation approach, expected impact, and any open questions or uncertainties to the same extent as a contribution made without tool assistance.

An important implication of this policy is that it bans agents that take action in our digital spaces without human approval, such as the GitHub @claude agent. Similarly, automated review tools that publish comments without human review are not allowed. However, an opt-in review tool that keeps a human in the loop is acceptable under this policy. As another example, using an LLM to generate documentation, which a contributor manually reviews for correctness, edits, and then posts as a PR, is an approved use of tools under this policy.

AI tools must not be used to fix GitHub issues labelled good first issue. These issues are generally not urgent, and are intended to be learning opportunities for new contributors to get familiar with the codebase. Fully automating the process of fixing this issue squanders the learning opportunity and doesn’t add much value to the project. New contributors using AI tools to fix issues labelled as “good first issues” is forbidden.

Finally, new contributors not recognized by the maintainers should first meet a project maintainer in a non-textual format before their first contribution will be accepted. This includes:

Meeting a maintainer in person.
Attending office hours or a working group meeting (cf. our community calendar).
Scheduling a video call with a maintainer (reach out via Discord or email).

New PRs from unrecognized contributors that appear to be AI-generated will be closed with a reference to this policy. New issues or issue comments from unrecognized contributors will be directed to this policy.

Extractive Contributions

The reason for our “human-in-the-loop” contribution policy is that processing patches, PRs, RFCs, and comments is not free – it takes a lot of maintainer time and energy to review those contributions! Sending the unreviewed output of an LLM to open source project maintainers extracts work from them in the form of design and code review, so we call this kind of contribution an “extractive contribution”.

Our golden rule is that a contribution should be worth more to the project than the time it takes to review it. These ideas are captured by this quote from the book Working in Public by Nadia Eghbal:

“When attention is being appropriated, producers need to weigh the costs and benefits of the transaction. To assess whether the appropriation of attention is net-positive, it’s useful to distinguish between extractive and non-extractive contributions. Extractive contributions are those where the marginal cost of reviewing and merging that contribution is greater than the marginal benefit to the project’s producers. In the case of a code contribution, it might be a pull request that’s too complex or unwieldy to review, given the potential upside.” – Nadia Eghbal

Prior to the advent of LLMs, open source project maintainers would often review any and all changes sent to the project simply because posting a change for review was a sign of interest from a potential long-term contributor. While new tools enable more development, it shifts effort from the implementer to the reviewer, and our policy exists to ensure that we value and do not squander maintainer time.

Reviewing changes from new contributors is part of growing the next generation of contributors and sustaining the project. We want the HEIR project to be welcoming and open to aspiring scientists and engineers who are willing to invest time and effort to learn and grow, because growing our contributor base and recruiting new maintainers helps sustain the project over the long term.

Handling Violations

If a maintainer judges that a contribution doesn’t comply with this policy, they should paste the following response to request changes:

This PR doesn't appear to comply with our policy on tool-generated content,
and requires additional justification for why it is valuable enough to the
project for us to review it. Please see our developer policy on
AI-generated contributions: https://heir.dev/docs/development/ai_policy/

The best ways to make a change less extractive and more valuable are to reduce its size or complexity or to increase its usefulness to the community. These factors are impossible to weigh objectively, and our project policy leaves this determination up to the maintainers of the project, i.e. those who are doing the work of sustaining the project.

If or when it becomes clear that a GitHub issue or PR is off-track and not moving in the right direction, maintainers should apply the extractive label to help other reviewers prioritize their review time.

If a contributor responds but doesn’t make their change meaningfully less extractive, maintainers should escalate to the relevant admin to lock the conversation.

References

Our policy was informed by experiences in other communities:

Fedora Council Policy Proposal: Policy on AI-Assisted Contributions (fetched 2025-10-01): Some of the text above was copied from the Fedora project policy proposal, which is licensed under the Creative Commons Attribution 4.0 International License. This link serves as attribution.
Rust draft policy on burdensome PRs
Seth Larson’s post on slop security reports in the Python ecosystem
The METR paper Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity.
QEMU bans use of AI content generators
Slop is the new name for unwanted AI-generated content

Docs: Bazel tips

Mon, 01 Jan 0001 00:00:00 +0000

Bazel cheat sheet

Commands

Task	Command
Build everything (slow)	`bazel build //...:all`
Build tests not marked as manual	`bazel build --build_tag_filters=-manual //...:all`
Build a specific library target	`bazel build //lib/Dialect/Polynomial/IR\:Dialect`
Build heir-opt	`bazel build //tools:heir-opt`
List targets in a directory	`bazel query //lib/Dialect/Polynomial/IR\:all`
Run all tests	`bazel test //...:all`
Run a subset of tests by path	`bazel test //tests/Dialect/...`
Run unit tests	`bazel test //lib/...:all`
Run lit and end-to-end tests	`bazel test //tests/...:all`
Run only lit tests (fast)	`bazel test $(bazel query 'filter("\.mlir\.test$", //...)')`
Run end-to-end tests (slow)	`bazel test //tests/Examples/...:all`
Clear build cache	`bazel clean`
Clear build cache and system analysis (where is clang, etc.)	`bazel clean --expunge`

Bazel flags

These flags are for bazel, and so they go before the target, and before any -- that separates flags for bazel from flags for the binary target being run, i.e., heir-opt or heir-translate. These can also be persistently configured in a .bazelrc file.

Flag	Description
`-c opt`	Build with optimizations enabled (`-O3`).
`-c dbg`	Build with debug symbols (better stack traces)
`-c fastbuild`	Sets compiler flags to optimize for fast build time
`--subcommands`	Shows subcommands that bazel invokes while building (e.g., raw `clang` or `heir-opt` commands run.
`--test_tag_filters` and `--build_tag_filters`	Filter targets by the `tag` set on the build target. E.g., `--build_tag_filters=-manual` will exclude any targets with the `manual` tag.

BUILD file formatting

The buildifier tool can be used to format BUILD files. You can download the latest Buildifier release from the Bazel Release Page. See IDE configuration for tips on integrating this with your IDE.

Avoiding rebuilds

Bazel is notoriously fickle when it comes to deciding whether a full rebuild is necessary, which is bad for HEIR because rebuilding LLVM from scratch takes 15 minutes or more. We try to avoid this as much as possible by setting default options in the project root’s .bazelrc.

The main things that cause a rebuild are:

Pulling an update from the remote main branch. The pinned LLVM commit is updated roughly once a day via automation (example commit) and changing that commit triggers a full rebuild of LLVM.
A change to the .bazelrc that implicitly causes a flag change. Note HEIR has its own project-specific .bazelrc in the root directory.
A change to the command-line flags passed to bazel, e.g., -c opt vs -c dbg for optimization level and debug symbols. The default is -c dbg, and you may want to override this to optimize performance of generated code. For example, the OpenFHE backend generates much faster code when compiled with -c opt.
A change to relevant command-line variables, such as PATH, which is avoided by the incompatible_strict_action_env flag. Note activating a python virtualenv triggers a PATH change. The default is incompatible_strict_action_env=true, and you would override this in the event that you want your shell’s environment variables to change and be inherited by bazel.

Pointing HEIR to a local clone of `llvm-project`

Occasionally changes in HEIR will need to be made in tandem with upstream changes in MLIR. In particular, we occasionally find upstream bugs that only occur with HEIR passes, and we are the primary owners/users of the upstream polynomial dialect.

To tell bazel to use a local clone of llvm-project instead of a pinned commit hash, replace bazel/import_llvm.bzl with the following file:

cat > bazel/import_llvm.bzl << EOF
"""Provides the repository macro to import LLVM."""

def import_llvm(name):
 """Imports LLVM."""
 native.new_local_repository(
 name = name,
 # this BUILD file is intentionally empty, because the LLVM project
 # internally contains a set of bazel BUILD files overlaying the project.
 build_file_content = "# empty",
 path = "/path/to/llvm-project",
 )
EOF

The next bazel build will require a full rebuild if the checked-out LLVM commit differs from the pinned commit hash in bazel/import_llvm.bzl.

Note that you cannot reuse the LLVM CMake build artifacts in the bazel build. Based on what you’re trying to do, this may require some extra steps.

If you just want to run existing MLIR and HEIR tests against local llvm-project changes, you can run the tests from HEIR using bazel test @llvm-project//mlir/...:all. New lit tests can be added in llvm-project’s existing directories and tested this way without a rebuild.
If you add new CMake targets in llvm-project, then to incorporate them into HEIR you need to add new bazel targets in llvm-project/utils/bazel/llvm-project-overlay/mlir/BUILD.bazel. This is required if, for example, a new dialect or pass is added in MLIR upstream.

Send any upstream changes to HEIR-relevant MLIR files to @j2kun (Jeremy Kun) who has LLVM commit access and can also suggest additional MLIR reviewers.

Finding upstream dependency targets

Whenever a new dependency is added in C++ or Tablegen, a new bazel BUILD dependency is required, which requires finding the path to the relevant target that provides the file you want. In HEIR the BUILD target should be defined in the same directory as the file you want to depend on (e.g., the targets that provide foo.h are in BUILD in the same directory), but upstream MLIR’s bazel layout is different.

LLVM’s bazel overlay for MLIR is contained in a single file, and so you can manually look there to find the right target. With bazel, if you know the filepath of interested you can also run:

bazel query --keep_going 'same_pkg_direct_rdeps(@llvm-project//mlir:<path>)'

where <path> is the path relative to mlir/ in the llvm-project project root. For example, to find the target that provides mlir/include/mlir/Pass/PassBase.td, run

bazel query --keep_going 'same_pkg_direct_rdeps(@llvm-project//mlir:include/mlir/Pass/PassBase.td)'

And the output will be something like

@llvm-project//mlir:PassBaseTdFiles

You can find more examples and alternative queries at the Bazel query docs.

Docs: Boilerplate tools

Mon, 01 Jan 0001 00:00:00 +0000

The script scripts/templates/templates.py contains commands for generating new dialects and transforms, filling in most of the boilerplate Tablegen and C++. These commands do not add the code needed to register the new passes or dialects in heir-opt.

These should be used when the tablegen files containing existing pass definitions in the expected filepaths are not already present. Otherwise, you must modify the existing tablegen files directly.

Run python scripts/templates/templates.py --help and python scripts/templates/templates.py <subcommand> --help for the available commands and options.

Creating a New Pass

General passes

If the pass does not operate from and to a specific dialect, use something similar to:

python scripts/templates/templates.py new_transform \
--pass_name=ForgetSecrets \
--pass_flag=forget-secrets

Dialect Transforms

To create a pass that operates within on a dialect, run a command similar to:

python scripts/templates/templates.py new_dialect_transform \
--pass_name=ForgetSecrets \
--pass_flag=forget-secrets \
--dialect_name=Secret \
--dialect_namespace=secret

Conversion Pass

To create a new conversion pass, i.e., a pass that lowers from one dialect to another, run a command similar to:

python scripts/templates/templates.py new_conversion_pass \
--source_dialect_name=CGGI \
--source_dialect_namespace=cggi \
--source_dialect_mnemonic=cggi \
--target_dialect_name=TfheRust \
--target_dialect_namespace=tfhe_rust \
--target_dialect_mnemonic=tfhe_rust

In order to build the resulting code, you must fix the labeled FIXMEs in the type converter and the op conversion patterns.

Creating a New Dialect

To create a new dialect, run something like

python scripts/templates/templates.py new_dialect \
--dialet_name=TensorExt \
--dialect_namespace=tensor_ext \
--enable_attributes=False \
--enable_types=True \
--enable_ops=True

Note that all --enable flags are True by default, so if you know your dialect will not have attributes or types, you have to explicitly disable those options.

Docs: IDE configuration

Mon, 01 Jan 0001 00:00:00 +0000

heir-lsp

HEIR provides an LSP server that extends the MLIR LSP server with HEIR’s dialects.

Build the LSP binary, then move it to a location on your path or point your IDE to bazel-bin/tools/heir-lsp.

bazel build //tools:heir-lsp
cp bazel-bin/tools/heir-lsp /usr/local/bin

Note that if you change any HEIR dialects, or if HEIR’s dependency on MLIR updates and the upstream MLIR has dialect changes (which happens roughly daily), you need to rebuild heir-lsp for it to recognize the changes.

clangd

Most IDE configured to use clangd can be powered from a file called compile_commands.json. To generate that for HEIR, run

bazel run @hedron_compile_commands//:refresh_all

This will need to be regenerated when there are major BUILD file changes. If you encounter errors like *.h.inc not found, or syntax errors inside these files, you may need to build those targets and then re-run the refresh_all command above.

Note that you will most likely also need to install the actual clangd language server, e.g., sudo apt-get install clangd on debian/ubuntu.

ibazel file watcher

ibazel is a shell around bazel that watches a build target for file changes and automatically rebuilds.

ibazel build //tools:heir-opt

VS Code

While a wide variety of IDEs and editors can be used for HEIR development, we currently only provide support for VSCode.

Setup

For the best experience, we recommend following these steps:

Install the MLIR, clangd and Bazel extensions
Install and rename Buildifier:

You can download the latest Buildifier release, e.g., for linux-amd64 (see the Bazel Release Page for a list of available binaries):
```
wget -c https://github.com/bazelbuild/buildtools/releases/latest/download/buildifier-linux-amd64
mv buildifier-linux-amd64 buildifier
chmod +x buildifier
```
Just as with bazel, you will want to move this somewhere on your PATH, e.g.:
```
mkdir -p ~/bin
echo 'export PATH=$PATH:~/bin' >> ~/.bashrc
mv buildifier ~/bin/buildifier
```
VS Code should automatically detect buildifier. If this is not successful, you can manually set the “Buildifier Executable” setting for the Bazel extension (bazel.buildifierExecutable).
Disable the C/C++ (aka ‘cpptools’) extension (either completely, or in the current workspace).
Add the following snippet to your VS Code user settings found in .vscode/settings.json to enable autocomplete based on the compile_commands.json file (see above).
```
 "clangd.arguments": [
 "--compile-commands-dir=${workspaceFolder}/",
 "--completion-style=detailed",
 "--query-driver=**"
 ],
```
For Python formatting, HEIR uses pyink for autoformatting, which is a fork of the more commonly used black formatter with some patches to support Google’s internal style guide. To use it in VSCode, install pyink along with other python utilities needed for HEIR: pip install -r requirements.txt and install the Black Formatter extension, then add the following to your VSCode user settings (.vscode/settings.json):
```
"[python]": {
 "editor.defaultFormatter": "ms-python.black-formatter"
},
"black-formatter.path": [
 "path/to/pyink"
]
```
It might be necessary to add the path to your buildifier to VSCode, though it should be auto-detected.
- Open the heir folder in VSCode
- Go to ‘Settings’ and set it on the ‘Workspace’
- Search for “Bazel Buildifier Executable”
- Once you find it, write [home-directory]/bin/buildifier for your specific [home-directory].

Building, Testing, Running and Debugging with VSCode

Building

Open the “Explorer” (File Overview) in the left panel.
Find “Bazel Build Targets” towards the bottom of the “Explorer” panel and click the dropdown button.
Unfold the heir folder
Right-click on “//tools” and click the “Build Package Recursively” option

Testing

Open the “Explorer” (File Overview) in the left panel.
Find “Bazel Build Targets” towards the bottom of the “Explorer” panel and click the dropdown button.
Unfold the heir folder
Right-click on “//test” and click the “Test Package Recursively” option

Running and Debugging

Create a launch.json file in the .vscode folder, changing the "name" and "args" as required:

{
 "version": "0.2.0",
 "configurations": [
 {
 "name": "Debug Secret->BGV",
 "preLaunchTask": "build",
 "type": "lldb",
 "request": "launch",
 "program": "${workspaceFolder}/bazel-bin/tools/heir-opt",
 "args": [
 "--secret-to-bgv",
 "--debug",
 "${workspaceFolder}/tests/secret_to_bgv/ops.mlir"
 ],
 "relativePathBase": "${workspaceFolder}",
 "sourceMap": {
 "proc/self/cwd": "${workspaceFolder}",
 "/proc/self/cwd": "${workspaceFolder}"
 }
 },
 ]
}

You can add as many different configurations as necessary.

Add Breakpoints to your program as desired.
Open the Run/Debug panel on the left, select the desired configuration and run/debug it.

Note that you might have to hit “Enter” to proceed past the Bazel build. It might take several seconds between hitting “Enter” and the debug terminal opening.

Vim/Neovim

Misc config

Filetype detection

# ftdetect/mlir.vim
au BufRead,BufNewFile *.mlir setfiletype mlir

Buildifier integration

# ftplugin/bzl.vim
augroup AutoFormat
 autocmd!
 autocmd BufWritePre Neoformat buildifier
augroup END

LSP configuration (Neovim, using nvim-lspconfig)

nvim_lsp["mlir_lsp_server"].setup {
 on_attach = on_attach,
 capabilities = capabilities,
 cmd = { "heir-lsp" },
}

Tree-sitter configuration for relevant project languages

require('nvim-treesitter.configs').setup {
 ensure_installed = {
 "markdown_inline", -- for markdown in tablegen
 "mlir",
 "tablegen",
 "verilog", -- for yosys
 },

 -- <... other config options ...>
}

Telescope-alternate config (quickly jump between cc, header, and tablegen files)

require('telescope-alternate').setup({
 mappings = {
 {
 pattern = '**/(.*).h',
 targets = {
 { template = '**/[1].cc', label = 'cc', enable_new = false },
 { template = '**/[1].cpp', label = 'cpp', enable_new = false },
 { template = '**/[1]Test.cc', label = 'cc Test', enable_new = false },
 { template = '**/[1]Test.cpp', label = 'cpp Test', enable_new = false },
 { template = '**/[1].td', label = 'tablegen', enable_new = false },
 }
 },
 {
 pattern = '**/(.*).cc',
 targets = {
 { template = '**/[1].h', label = 'header', enable_new = false },
 { template = '**/[1].cpp', label = 'cpp', enable_new = false },
 { template = '**/[1]Test.cc', label = 'cc Test', enable_new = false },
 { template = '**/[1]Test.cpp', label = 'cpp Test', enable_new = false },
 { template = '**/[1].td', label = 'tablegen', enable_new = false },
 }
 },
 {
 pattern = '**/(.*).cpp',
 targets = {
 { template = '**/[1].h', label = 'header', enable_new = false },
 { template = '**/[1].cc', label = 'cc', enable_new = false },
 { template = '**/[1]Test.cc', label = 'test', enable_new = false },
 { template = '**/[1]Test.cpp', label = 'test', enable_new = false },
 { template = '**/[1].td', label = 'tablegen', enable_new = false },
 }
 },
 {
 pattern = '**/(.*).td',
 targets = {
 { template = '**/[1].h', label = 'header', enable_new = false },
 { template = '**/[1].cc', label = 'cc', enable_new = false },
 { template = '**/[1].cpp', label = 'cpp', enable_new = false },
 }
 },
 {
 pattern = '(.*)Test.(.*)',
 targets = {
 { template = '**/[1].[2]', label = 'implementation', enable_new = false },
 }
 },
 },
 open_only_one_with = 'vertical_split',
})

Useful mappings

Navigate to the bazel build target for current file

vim.keymap.set('n', '<leader>eb', function()
 -- expand("%:p:h") gets the current filepath
 local buildfile = vim.fn.expand("%:p:h") .. "/BUILD"
 -- expand("%:t") gets the current filename with suffix.
 local target = vim.fn.expand("%:t")
 vim.api.nvim_command("botright vsplit " .. buildfile)
 vim.cmd("normal /" .. target .. vim.api.nvim_replace_termcodes("<CR>", true, true, true))
 vim.cmd("normal zz")
end,
 { noremap = true })

Set include guards according to HEIR style guide.

local function build_include_guard()
 -- project relative filepath
 local abs_path = vim.fn.expand("%")
 local rel_path = vim.fn.fnamemodify(abs_path, ":~:.")

 -- screaming case
 local upper = string.upper(rel_path)
 -- underscore separated
 local underscored = string.gsub(upper, "[./]", "_")
 -- trailing underscore
 return underscored .. "_"
end

-- mnemonic: fi = fix include (guard)
vim.keymap.set('n', '<leader>fi', function()
 local buf = vim.api.nvim_get_current_buf()
 local include_guard = build_include_guard()
 local ifndef = "#ifndef " .. include_guard
 local define = "#define " .. include_guard
 local endif = "#endif // " .. include_guard

 vim.api.nvim_buf_set_lines(buf, 0, 2, false, { ifndef, define })
 vim.api.nvim_buf_set_lines(buf, -2, -1, false, { endif })
end, { noremap = true })

HEIR – Development

Docs: AI Tool Use Policy

Policy

Details

Extractive Contributions

Handling Violations

References

Docs: Bazel tips

Bazel cheat sheet

Commands

Bazel flags

BUILD file formatting

Avoiding rebuilds

Pointing HEIR to a local clone of llvm-project

Finding upstream dependency targets

Docs: Boilerplate tools

Creating a New Pass

General passes

Dialect Transforms

Conversion Pass

Creating a New Dialect

Docs: IDE configuration

heir-lsp

clangd

ibazel file watcher

VS Code

Setup

Building, Testing, Running and Debugging with VSCode

Building

Testing

Running and Debugging

Vim/Neovim

Misc config

Useful mappings

Pointing HEIR to a local clone of `llvm-project`