Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Deepak-Sangle/TornadoVM/llms.txt

Use this file to discover all available pages before exploring further.

TornadoVM is a 10+ year open-source project maintained by a small but dedicated research team at The University of Manchester. Contributions are warmly welcomed — whether you’re fixing a bug, improving documentation, adding a new use-case, or extending the runtime itself. This page walks you through every step of the process, from forking the repository to getting your pull request reviewed and merged.

​
Contribution Workflow

Every change to TornadoVM flows through a pull request (PR) targeting the develop branch. The main branch always reflects the latest stable release, so never open a PR directly against main.
1

Fork and Clone

Fork the TornadoVM repository on GitHub, then clone your fork locally:
git clone https://github.com/<your-username>/TornadoVM.git
cd TornadoVM
2

Create a Branch from develop

Always branch from develop — not main — to include the latest in-flight changes:
git checkout develop
git pull upstream develop          # keep your local develop up to date
git checkout -b fix/my-branch-name
Use descriptive prefixes such as fix/, feat/, or docs/ to signal the intent of your branch.
3

Commit Your Changes

Stage and commit with a clear, descriptive message:
git add <yourFiles>
git commit -m "feat: add cuSPARSE SpMM batched variant"
Keep commits focused. A single logical change per commit makes review and potential bisecting far easier.
4

Push and Open the Pull Request

Push to your fork and open a PR against the develop branch of the upstream repository:
git push -u origin fix/my-branch-name
On GitHub, navigate to the upstream repo and choose New pull request → develop.
Before opening your PR, make sure your branch is merged with the latest develop changes (git rebase upstream/develop or git merge upstream/develop) and that your code passes all formatter checks.

​
Review Process

The TornadoVM team performs thorough reviews that cover correctness, performance, portability across backends (OpenCL, PTX, CUDA, Metal), and long-term maintainability. Plan for a few rounds of feedback — this is normal and helps maintain the project’s high standards.

CI Checks

Every PR triggers automated GitHub Actions: a code formatter check verifies style compliance, a documentation render validates MDX/RST pages, and a CLA check confirms you have signed the Contributor License Agreement.

Two-Reviewer Minimum

At least two researchers or engineers from the TornadoVM team must approve your PR before it can be merged. Expect questions, inline comments, and possible change requests.

Internal Test Suite

The team runs your PR against a full regression suite on real GPU hardware — NVIDIA (CUDA/PTX), Intel, and AMD via OpenCL — on multiple driver versions and operating systems. This takes time for a small team.

Patience Appreciated

Because the team is small and the test matrix is large, review timelines vary. Complex PRs touching the JIT compiler or a backend may take longer. You can always ping the thread politely.

​
Signing the CLA

When you open your first PR, the CLA-assistant bot will comment with a link to the TornadoVM Contributor License Agreement at cla-assistant.io/beehive-lab/TornadoVM. You must sign it using the same email address you use for your Git commits, otherwise the CI check will block merging.
Check that your commit email matches your GitHub-registered email with git config user.email. You can set it per-repo with git config user.email "you@example.com" if needed.
The CLA is a one-time action — once signed it applies to all future contributions.

​
Coding Conventions

TornadoVM enforces a uniform code style via the Eclipse auto-formatter. Your PR’s CI run will fail if the formatter detects violations, so apply it locally before pushing.
Run the provided setup script, which installs the Eclipse formatter configuration into your workspace automatically:
mvn eclipse:eclipse
python3 scripts/eclipseSetup.py
NetBeans users should additionally install the Eclipse Formatter Plugin for NetBeans so the same XML config is respected inside the IDE.

​
Setting Up IntelliJ Run Configurations

After building TornadoVM, you can auto-generate IntelliJ run configurations for build targets and test suites, making it easy to run and debug directly from the IDE.
1

Build TornadoVM

make
2

Load Environment Variables

source setvars.sh
3

Generate IntelliJ Project Files

make intellijinit
This writes run configurations into the .build/ directory. IntelliJ detects them automatically; browse them via Run → Edit Configurations.

​
Running Tests

TornadoVM’s test suite covers all backends, data types, and API surfaces. Always run at least the fast tests locally before opening a PR. 
# Verbose output with assertions enabled
tornado-test --ea --verbose

# Or via the Makefile target
make tests
If you have both the OpenCL and CUDA backends installed, unit tests may silently run on the OpenCL device and report false positives for CUDA-specific features. Build with a single backend (make BACKEND=cuda) when testing CUDA-specific functionality.

​
Finding Work to Do

Good First Issues

Browse GitHub issues labelled good first issue for well-scoped, beginner-friendly tasks with clear acceptance criteria.

Ideas & Proposals

Have a bigger idea? Open a proposal in GitHub Discussions or share a Google Doc. The team reviews proposals before large implementation efforts begin.

Documentation

Improve install guides, add tested-platform matrices, write tutorials for new use-cases (e.g., NBody visualisation, blockchain, image filters).

Benchmarks & Tooling

Implement a performance-plot suite for the benchmark runner — speedup charts vs. serial Java, plus breakdown bars for compilation, execution, and data transfer time.

​
Community and Contact

The primary async community space is GitHub Discussions. Use it to ask questions, share proposals, or report usage experiences. Please follow the Code of Conduct in all community spaces — the project is committed to a harassment-free, inclusive environment for contributors of all backgrounds.
TornadoVM maintains a Slack workspace for real-time discussion. Reach out to the maintainers via email (below) to request an invitation if you’d like to join.
For proposals or technical discussions that don’t fit a public issue, you can email the core team directly:
NameRoleEmail
Christos KotselidisLead Maintainerchristos.kotselidis @ manchester.ac.uk
Athanasios StratikopoulosCore Engineerathanasios.stratikopoulos @ manchester.ac.uk
Michail PapadimitriouCore Engineermichail.papadimitriou @ manchester.ac.uk

Build docs developers (and LLMs) love

Get started for freeTalk to us