Contributing

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

Report an issue or propose a feature

Search the Codeberg 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 the Plugin DevKit installed
• One of the following environments for working with the bundled Python runtime:
  • PyCharm 2026
  • IntelliJ IDEA 2026 with both Python and Python Community Edition installed
• Git and a Codeberg account
• Blender 4.2 or newer for changes that require live integration testing

Set up the project

1. Fork the Blender Development repository on Codeberg.
2. Clone your fork using the clone URL shown on its Codeberg page.
3. Create a focused branch for the change.
4. Open the repository as a Gradle project in IntelliJ IDEA 2026.
5. Confirm that Plugin DevKit is enabled. If you use IntelliJ IDEA instead of PyCharm for the Python runtime, also confirm that both Python and Python Community Edition are enabled.
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

IntelliJ IDEA and Plugin DevKit provide the IntelliJ Platform plugin-development environment. PyCharm, or the two Python plugins for IntelliJ IDEA, provide the tooling needed to work with the Python runtime. The Gradle build packages src/main/python into the Blender runtime archive when processing plugin resources.

Make a focused change

• Use Kotlin for new JVM code and follow the conventions in the surrounding files.
• Keep functions focused and prefer existing IntelliJ Platform services and project patterns.
• Put user-visible strings in messages/MessageBundle.properties so they can be localized.
• Add KDoc to new public classes and functions.
• Keep service and extension IDs stable unless the change intentionally includes a migration.
• Avoid blocking the Event Dispatch Thread with file, network, or process work.
• Add or update tests for new behavior, regressions, and meaningful edge cases.
• Update the 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 the change affects discovery, launch, debugging, add-on loading, extensions, or runtime commands.

Validate changes

Run checks proportional to the change. At minimum, compile the Kotlin sources 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 be run, explain what was skipped and why in the pull 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 using the repository format: [Type -> module] Description. Omit -> module when the change spans three or more modules.
3. Push the branch to your fork.
4. Open a pull request against the original Codeberg repository.
5. Summarize the problem and solution, list the validation performed, and disclose known limitations or skipped checks.
6. Link the issue addressed by the change when one exists.

Keep the pull request focused enough to review and test independently. Respond to review feedback with additional commits until the change is ready to merge.

Licensing

Blender Development is licensed under the GNU General Public License v3.0 or later. By submitting a contribution, ensure you have the right to provide the code, documentation, or assets under the project’s license.