Contributing

Contributions can include bug reports, feature proposals, translations, documentation, tests, and source-code changes.

Report an issue or propose a feature

Search the GitLab issue tracker before opening an issue. If no existing issue covers your case, include:

• The Blender Development, PyCharm, operating-system, and Blender versions involved
• Clear steps to reproduce the behavior
• What you expected and what happened instead
• Relevant logs or screenshots with credentials and personal information removed

For feature proposals, describe the workflow the feature would improve rather than only the proposed implementation.

Prerequisites

• JDK 21
• Network access for the first Gradle dependency resolution
• IntelliJ IDEA 2026 with Plugin DevKit installed
• One of these environments for the bundled Python runtime:
  • PyCharm 2026
  • IntelliJ IDEA 2026 with both Python and Python Community Edition installed
• Git and a GitLab account
• Blender 4.2 or newer for live integration testing

Set up the project

1. Fork the Blender Development repository on GitLab.
2. Clone your fork using the URL shown on its GitLab page.
3. Create a focused branch for the change.
4. Open the repository as a Gradle project in IntelliJ IDEA 2026.
5. Confirm Plugin DevKit is enabled. In IntelliJ IDEA, also enable Python and Python Community Edition.
6. Set the project SDK to JDK 21 and allow Gradle to resolve the IntelliJ Platform dependencies.
7. Confirm the project compiles:

./gradlew compileKotlin --no-daemon

The Gradle build packages src/main/python into the Blender runtime archive while processing plugin resources.

Make a focused change

• Use Kotlin for new JVM code and follow surrounding conventions.
• Put user-visible strings in messages/MessageBundle.properties.
• Add KDoc to new public classes and functions.
• Keep service and extension IDs stable unless the change includes a migration.
• Do not block Swing’s Event Dispatch Thread with file, network, or process work.
• Add or update tests for new behavior, regressions, and meaningful edge cases.
• Update public documentation when a user-facing workflow or setting changes.

Run the plugin

./gradlew runIde

This opens a sandbox PyCharm instance with the development build installed. Exercise the affected workflow there, including both Run and Debug behavior when changing process or runtime integration.

Live Blender behavior is not covered by the JVM test suite. Test against a compatible Blender installation when changing discovery, launch, debugging, add-on loading, extensions, or runtime commands.

Validate changes

At minimum, compile Kotlin and run the test suite:

./gradlew compileKotlin --no-daemon
./gradlew test --no-daemon

Build the distributable plugin when changing dependencies, build metadata, packaged resources, or the bundled Python runtime:

./gradlew buildPlugin

If a relevant check cannot run, explain what was skipped and why in the merge request.

Tip

Use ./gradlew tasks --all to inspect available build and packaging tasks.

Submit the change

1. Review the diff and exclude generated files, IDE metadata, credentials, and unrelated changes.
2. Commit complete work as [Type -> module] Description. Omit -> module when the change spans three or more modules.
3. Push the branch to your fork.
4. Open a merge request against the original GitLab repository.
5. Summarize the problem and solution, list validation, and disclose known limitations or skipped checks.
6. Link the issue addressed by the change when one exists.

Keep the merge request focused enough to review and test independently.

Licensing

Blender Development is licensed under the GNU General Public License v3.0 or later. By submitting a contribution, ensure you can provide the code, documentation, or assets under that license.