Thank you for your interest in contributing to TileGym! This document explains the main ways you can help and what we expect from contributions.

• Report issues

  • Use the issue tracker to report bugs, request features, or suggest improvements.
  • Include clear steps to reproduce, expected vs. actual behavior, and environment details when possible.

• Contribute code

  • See Code contributions for the end-to-end workflow and expectations.
  • See Contributing kernels for kernel work (new kernels vs. optimizing existing kernels).

Before starting non-trivial work, please check for existing issues and consider opening a discussion/issue so we can align on scope and design.

If you plan to submit code changes (new features, bug fixes, refactors):

1. Review the Roadmap

   • Before contributing, please review the ROADMAP.md to understand:
     • Current operator support status (what's available, in progress, or planned)
     • Contribution opportunities and priority areas
     • Which kernels need help (marked as "🙋 Help Wanted")
   • This helps ensure your contribution aligns with project priorities and avoids duplicate work.

2. Read the project README

   • Review the project-level README.md for build, install, and basic usage instructions.

3. Pick or propose an issue

   • Look for existing issues that match what you want to do, or create a new issue describing your proposal.
   • Comment on the issue to indicate you are working on it.

4. Discuss significant changes first

   • For larger features or intrusive refactors, outline your approach in the issue so maintainers can provide feedback early.

5. Implement the change

   • Follow the existing coding style and patterns in the affected modules.
   • Add or update tests to cover new behavior.
   • If you are contributing kernel code, follow Contributing kernels.

6. Format your code

   • Run ./format.sh from the repository root to ensure your changes pass CI format checks.

7. Open a pull request

   • Keep PRs focused on a single logical change.
   • Describe what the PR does, how you tested it, and any potential user-facing impact.

8. Respond to review

   • Address comments, push updates, and keep the discussion on the PR/issue.

There are two common situations when contributing kernel code:

• Situation A: Add a new kernel (or a new op)
• Situation B: Optimize or update an existing kernel

If you are adding a new kernel (new @ct.kernel / new op implementation) that is not yet validated by the core team, it should go through the experimental-kernel flow.

New cuTile kernel contributions should first be placed in the experimental/ directories. Once the TileGym team has fully verified functional correctness and performance, kernels will be promoted from experimental/ into the main source tree.

We provide tilegym-adding-cutile-kernel skill for AI agent to add new kernels in this repo.

src/tilegym/ops/cutile/experimental/<kernel_name>.py   # kernel implementation
tests/ops/experimental/test_<kernel_name>.py            # correctness tests
tests/benchmark/experimental/bench_<kernel_name>.py     # performance benchmarks

Create src/tilegym/ops/cutile/experimental/<kernel_name>.py.

• Import experimental_kernel via from tilegym.experimental import experimental_kernel.
• Apply the @experimental_kernel decorator before @ct.kernel.
• Use @register_impl on the op entry-point function.
• See src/tilegym/ops/cutile/experimental/mhc.py for an example.

The @experimental_kernel decorator marks a kernel as experimental so that a one-time message is printed the first time the kernel is launched via ct.launch. Three usage forms:

@experimental_kernel                         # bare — auto-generates message from kernel name (recommended)
@experimental_kernel()                       # empty parens — same as bare
@experimental_kernel("Custom message text")  # custom message

• The bare form (recommended) auto-generates a message that includes the kernel's function name.
• The message prints once per kernel per process at the first ct.launch call.
• The decorator must be placed before @ct.kernel.

If your kernel introduces a new public op name (a new dispatch key that does not already exist), you need to add it to the unified API layer in src/tilegym/ops/ops.py:

1. Add a new function decorated with @dispatch("<op_name>").
2. Keep the public API signature stable and aligned with your implementation.
3. Ensure the dispatch key string matches exactly: @dispatch("<op_name>") in ops.py must match @register_impl("<op_name>", backend=...) in your backend implementation.

If you are providing a new backend implementation for an op that already exists in ops.py, you usually do not need to modify ops.py.

In src/tilegym/ops/cutile/__init__.py:

1. Add an import for your module (for example from .experimental import <module>) so the module is loaded and your @register_impl(...) registration runs.
2. If you want functions to be directly accessible from tilegym.ops.cutile, add from .experimental.<module> import <function>.
3. Add any directly-exported function names to __all__.

Create tests/ops/experimental/test_<kernel_name>.py.

• Inherit from common.PyTestCase.
• Implement a reference() method (or similar) that computes the expected result using PyTorch.
• Use @pytest.mark.parametrize for shape/dtype coverage and self.assertCorrectness() for validation.
• Add cases that cover typical shapes, edge cases, and mixed-precision scenarios where relevant.
• Make sure tests pass locally with pytest before opening the PR.
• See tests/ops/README.md for full testing guidelines.

Create tests/benchmark/experimental/bench_<kernel_name>.py.

Benchmarks in tests/benchmark/experimental/ are auto-discovered by run_all.sh and run_all_json.py — no extra registration is needed.

If you are optimizing or updating an existing kernel (for performance, correctness, maintainability, readability, portability, etc.) for an op that already exists, you typically only need to update the existing implementation file(s) and tests/benchmarks.

• No @experimental_kernel marker needed: you do not need to add @experimental_kernel when you are improving an already-existing kernel implementation. If the kernel already carries @experimental_kernel, keep the existing behavior unless maintainers request otherwise.
• No ops.py or registration changes needed in most cases, because the op is already dispatched. This includes helper kernels that are called inside an already-registered implementation.
• Follow the existing coding style and patterns in the affected modules.
• Add or update tests and benchmarks to verify your changes if needed: correctness tests under tests/ops/ and benchmarks under tests/benchmark/.

To accept your contribution, we need a signed Contributor License Agreement (CLA) on file.

1. Locate the CLA at LICENSES/CLA.md in this repository.
2. Fill it out and sign.
3. Email the signed CLA to TileGym@nvidia.com with subject: TileGym CLA Submission.
4. Wait for confirmation from the TileGym team before your PR can be merged.

Files under skills/ (also accessible via the .agents/skills/ and .claude/skills/ backward-compatibility symlinks) are dual-licensed under CC-BY-4.0 AND Apache-2.0 (see LICENSE). All contributions to the dual-licensed agent-skills content must be signed off via the Developer Certificate of Origin (DCO).

By signing off on a commit, you certify that the contribution is your original work, or that you have rights to submit it under the same license, or a compatible license. Any commit touching files under skills/ (or its .agents/skills/ / .claude/skills/ symlinks) that is not signed off will not be accepted.

Use the --signoff (or -s) option when committing your changes:

git commit -s -m "Add cool feature."

This appends a Signed-off-by: trailer to the commit message:

Signed-off-by: Your Name <your@email.com>

The trailer must use your real name and a verifiable email address (the one configured in git config user.email).

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.

• Maintainers will review your PR, suggest changes if needed, and approve once it meets project standards.
• CI and tests must pass before merge.
• Focused, well-described, and well-tested PRs are much easier and faster to review.

If anything in this document is unclear or missing, feel free to comment on issues and ask for clarifications!