Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
274 lines (207 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

274 lines (207 loc) · 10.5 KB

Contribution Guidelines

This purpose of this document is to describe how to contribute to Arm® KleidiAI™ and define what is expected from a contribution. It does not cover every corner case; the policy will evolve over time.

Before you start

Before starting non-trivial work, please read:

Reach out to the maintainers by creating a new issue on the official KleidiAI GitLab before investing significant time in:

  • New micro-kernels.
  • New public APIs.
  • Large rewrites, broad refactors, or changes that alter established micro-kernel behavior.

Accepted contributions

The following areas are generally suitable for external contributions:

  • New micro-kernels
  • Bug fixes
  • Example improvements and new examples that demonstrate supported usage.
  • Build-system fixes for supported build systems.
  • Test and benchmark improvements that follow the existing framework.

Rejected contributions

The following directories are not open to external contributions and contributions will be rejected without prior maintainer agreement:

  • experimental

KleidiAI does not accept contributions that add support for:

  • Non-Arm CPU architectures.
  • AArch32 execution state.
  • Unsupported operating systems, compiler families, or build systems unless maintainers have agreed to expand the support policy.
  • Breaking changes to the public API.

General contribution requirements

All contributions must:

  • Use one of the project licenses in the LICENSES sub-directory.
  • Include a Developer Certificate of Origin sign-off.
  • Preserve or add correct copyright and license metadata.
  • Follow the Coding standard and convention.
  • Build with all relevant supported build systems.
  • Include appropriate tests cases.
  • Update relevant documentation.
  • Include appropriate updates to CHANGELOG.md.

For contributions, a Developer Certificate of Origin (DCO) is required to certify origin. The process is managed by DCO v1.1.

The agreement to the DCO is indicated by a Signed-off-by line in the commit message using your real name and email address:

Signed-off-by: Name <name@example.com>

Contributors are responsible for ensuring their copyright notices are correct. Third party contributors should add their own copyright notice applicable to their own modifications in existing files. For new files, if they include any code copied from existing files, preserve the existing copyright as is (do not modify it in any way - for example changing the year) and amend as required with third party copyright notice. If the file is entirely new and does not contain Arm copyrightable content, there is typically no need to include Arm copyright.

Do not contribute code with unclear provenance and do not include code copied from licenses that are incompatible with KleidiAI distribution. Disclose third-party sources in the merge request.

Micro-kernel contributions

Discuss new micro-kernels with maintainers before implementation. The discussion should cover:

  • The operation and data formats.
  • The target architecture feature or microarchitecture.
  • Expected integration use case.
  • Expected performance benefit.
  • Whether the micro-kernel needs to expand the public API.
  • Required packing micro-kernels.
  • Test, benchmark, and documentation requirements.

New micro-kernels must:

  • Follow the established naming convention or explicitly justify an extension to it.
  • Use the current micro-kernel API style unless maintainers explicitly agree to a different interface.
  • Provide matching interface headers where required.
  • Preserve public symbol naming consistency.
  • Use ACLE feature test macros for CPU-feature-dependent code where applicable.
  • Maintain the advertised behavior, including clamp behavior and partial-output behavior.
  • Include unit tests. Must use the NextGen test framework which is described in docs/microkernel_testing.md.
  • Include benchmark test.
  • Be added to the micro-kernel tables in docs/microkernel_tables.md.

Getting access and submitting a merge request

Contributions are submitted as GitLab merge requests (MR). The process to submit a MR is:

  1. Create an account on the Arm hosted GitLab instance.
  2. Request project fork permission. See Arm GitLab contribution documentation.
  3. Fork the KleidiAI repository.
  4. Make the smallest coherent change that solves the problem.
  5. Run the relevant tests locally and fix any issues.
  6. Push the patch-set to your forked repository.
  7. Submit a MR on the official KleidiAI GitLab repository with a clear description.

The description of a MR must contain:

  • Prefix the first line with type of contribution: major, feat, fix, docs or chore
  • What changed.
  • Why the change is needed.
  • How it was tested.
  • Any remaining limitations or follow-up work.

Testing requirements

Never skip tests unless there is a clear unavoidable reason.

For normal validation, run one of:

cmake -S . -B build
cmake --build build
build/kleidiai_test
bazelisk test //test:kleidiai_test

The NextGen test framework uses deterministic seeds by default. For new micro-kernels, run with several explicit seeds to cover more generated shapes and values.

Benchmarking and performance evidence

Performance-sensitive contributions must include benchmark evidence. Build and run the benchmark tool as described in benchmark/README.md.

Performance evidence should include:

  • The exact hardware platform.
  • Operating system and toolchain version.
  • Build system and build flags.
  • Benchmark command lines.
  • Shape set used for testing.
  • Baseline commit or baseline micro-kernel.
  • Results for the changed implementation and the baseline.

Use shapes that represent the intended integration use case. When possible, choose shapes from existing model workloads rather than synthetic shapes only.

Examples and documentation

Add a new, or update one of the existing, standalone C++ example application(s) in the examples sub-directory when a change introduces a new concept users of the micro-kernel must understand in order to use the micro-kernel. Examples of when this is needed is when the contribution adds:

  • A new integration pattern.
  • A new operator flow not covered by existing examples.
  • A new public API that is not self-explanatory from existing documentation.

Before adding new explanatory text, check whether existing documentation can be referenced instead:

Pre-commit checks

Install and run the configured pre-commit hooks before submitting a merge request:

pre-commit install
pre-commit run --all-files

The hook configuration is in .pre-commit-config.yaml.

If a hook fails, fix the underlying issue rather than bypassing the hook. If a hook is not applicable to a specific change, explain that in the merge request.

Supported environments

KleidiAI support is intentionally bounded. Contributions must preserve support for the environments targeted by the project.

Library C sources must remain C99-compatible, with ACLE and assembly extensions where required for Arm architecture features. C++ code in tests and tooling must remain C++17-compatible unless maintainers agree otherwise.

The project supports CMake 3.16 and Bazel 6.5 or later. Contributions that add files or change build behavior must keep both build systems up to date.

OS / environment Supported versions Compiler / toolchain Supported versions / policy
Ubuntu Current LTS versions GCC Default GCC installation versions and all more recent supported releases on gcc.gnu.org
Ubuntu Current LTS versions Clang Default Clang installation versions and latest upstream Clang release
Ubuntu Supported Ubuntu versions where available Arm Compiler for Linux All ACfL releases from the previous 13 months
Windows® Windows releases marked (E) or (W) in Active Support: Windows 11 26H1 E/W, 25H2 E/W, 24H2 E/W, 23H2 E MSVC / Visual Studio® Visual Studio Stable Channel
macOS® operating system software macOS 26, 15, 14 Xcode® developer software Most recent minor release of the most recent major Xcode release
Android™ Android NDK Current Android NDK LTS

macOS and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries and regions.
Android is a trademark of Google LLC.
Visual Studio and Windows are trademarks of the Microsoft group of companies.

Review and acceptance process

Once a MR is uploaded, the KleidiAI maintainers will review it and trigger the CI pipeline. Maintainers review merge requests for:

  • Project fit.
  • Code maintainability.
  • Correctness and API behavior.
  • Test coverage.
  • Benchmark and performance evidence where relevant.
  • Build-system coverage.
  • Coding convention compliance.
  • Documentation quality.
  • Licensing and provenance.

Maintainers may ask for additional explanation or rewriting when the code is hard to review, inconsistent with project conventions, or has unclear origin.

Review comments must be addressed before merge. Keep updates focused and avoid unrelated refactoring while responding to review.

Acceptance of a contribution does not imply acceptance of follow-up work, new support scope, or future micro-kernels in the same area. Discuss major follow-up work with the maintainers.