From 77edaab16500b320da3bc0aa29128cdab6e3a177 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Mon, 21 Sep 2026 14:20:35 +0530 Subject: [PATCH 1/4] add latest learnings from version bumps and test module --- docs/source/builder/writing-kernels.md | 29 ++++++++++++++++++++++++++ docs/source/kernel-requirements.md | 4 ++++ 2 files changed, 33 insertions(+) diff --git a/docs/source/builder/writing-kernels.md b/docs/source/builder/writing-kernels.md index eb36c60f..c495d14f 100644 --- a/docs/source/builder/writing-kernels.md +++ b/docs/source/builder/writing-kernels.md @@ -545,6 +545,35 @@ $ nix run .#ciTests.torch210-cxx11-cpu-x86_64-linux When running the tests on a non-NixOS systems, make sure that [the CUDA driver library can be found](https://danieldk.eu/Software/Nix/Nix-CUDA-on-non-NixOS-systems#solutions). +### Misc + +If the tests need to access a module, not exposed in the public API +surface, do not use `importlib`. For example: + +```py +... + +importlib.import_module(f"{flash_attn4.__name__}.compute_block_sparsity") +BlockSparsityKernel = flash_attn4.compute_block_sparsity.BlockSparsityKernel +BlockSparseTensors = flash_attn4.block_sparsity.BlockSparseTensors +``` + +This pattern should be avoided. Instead, create a separate private +module and include the modules needed in the tests inside it. Then +expose that private module from the public API surface. So, the +`__init__.py` would look like so: + +```py +from . import _private_for_tesing + +__all__ = [ + "_private_for_testing", + ... +] +``` + +Where `_private_for_testing` would contain the modules needed for tests. + ## Kernel docs We provide a utility to generate a system card for a given kernel, utilizing diff --git a/docs/source/kernel-requirements.md b/docs/source/kernel-requirements.md index 14976c4e..21dbe673 100644 --- a/docs/source/kernel-requirements.md +++ b/docs/source/kernel-requirements.md @@ -310,6 +310,10 @@ replaced by the new build: - Torch stable ABI kernels, as long as the CUDA versions that get built overlap with the current build variants. +Note that even for noarch Python-only kernels, we need a version bump +where arguments are removed from the public API or change the default +for an argument present in the public API. + ## Native Python module Kernels will typically contain a native Python module with precompiled From 2b2234e4046ce6595d5173052376b43f06e0e479 Mon Sep 17 00:00:00 2001 From: Sayak Paul Date: Mon, 21 Sep 2026 16:33:35 +0530 Subject: [PATCH 2/4] Apply batched suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Daniël de Kok --- docs/source/builder/writing-kernels.md | 4 ++-- docs/source/kernel-requirements.md | 7 ++++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/builder/writing-kernels.md b/docs/source/builder/writing-kernels.md index c495d14f..73294f21 100644 --- a/docs/source/builder/writing-kernels.md +++ b/docs/source/builder/writing-kernels.md @@ -545,7 +545,7 @@ $ nix run .#ciTests.torch210-cxx11-cpu-x86_64-linux When running the tests on a non-NixOS systems, make sure that [the CUDA driver library can be found](https://danieldk.eu/Software/Nix/Nix-CUDA-on-non-NixOS-systems#solutions). -### Misc +### Tests that need access to internal APIs If the tests need to access a module, not exposed in the public API surface, do not use `importlib`. For example: @@ -559,7 +559,7 @@ BlockSparseTensors = flash_attn4.block_sparsity.BlockSparseTensors ``` This pattern should be avoided. Instead, create a separate private -module and include the modules needed in the tests inside it. Then +module named `_private_for testing` and include the modules needed in the tests inside it. Then expose that private module from the public API surface. So, the `__init__.py` would look like so: diff --git a/docs/source/kernel-requirements.md b/docs/source/kernel-requirements.md index 21dbe673..5a93a45d 100644 --- a/docs/source/kernel-requirements.md +++ b/docs/source/kernel-requirements.md @@ -310,9 +310,10 @@ replaced by the new build: - Torch stable ABI kernels, as long as the CUDA versions that get built overlap with the current build variants. -Note that even for noarch Python-only kernels, we need a version bump -where arguments are removed from the public API or change the default -for an argument present in the public API. +In the following cases no version bump is required for these types of kernels: + +- Adding new functions/methods/classes. +- Adding new arguments with default values to a function/method/constructor, as long as the default values do not change previous behavior. ## Native Python module From b259ed8cb6f16db8978bf4898522fd1df356bd68 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Mon, 21 Sep 2026 16:36:02 +0530 Subject: [PATCH 3/4] fix private module name --- docs/source/builder/writing-kernels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/builder/writing-kernels.md b/docs/source/builder/writing-kernels.md index 73294f21..b381f842 100644 --- a/docs/source/builder/writing-kernels.md +++ b/docs/source/builder/writing-kernels.md @@ -559,7 +559,7 @@ BlockSparseTensors = flash_attn4.block_sparsity.BlockSparseTensors ``` This pattern should be avoided. Instead, create a separate private -module named `_private_for testing` and include the modules needed in the tests inside it. Then +module named `_private_for_testing` and include the modules needed in the tests inside it. Then expose that private module from the public API surface. So, the `__init__.py` would look like so: From 3a149c0c46b7936862ce631f25dae7dd9edec42d Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 22 Sep 2026 17:54:36 +0530 Subject: [PATCH 4/4] up --- docs/source/kernel-requirements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/kernel-requirements.md b/docs/source/kernel-requirements.md index 5a93a45d..67fbd72e 100644 --- a/docs/source/kernel-requirements.md +++ b/docs/source/kernel-requirements.md @@ -298,8 +298,8 @@ fail on the build variants that were not rebuilt. ### Exceptions -A version bump is not needed when every existing build variant is -replaced by the new build: +For the following types of kernels, some API changes do not require +bumping the version: - Python-only (noarch) kernels, e.g. `torch-cuda`. All build variants get updated, so this issue does not exist.