CONTRIBUTING.md

Contributing to Spockk

Thank you for considering contributing to Spockk!

Getting Started

Before starting work on a significant change, please open an issue to discuss your proposal with the maintainers.

Development Setup

Prerequisites

• JDK 21: Set the JDK21 environment variable to the JDK path to make it discoverable by Gradle's toolchains.
• direnv: Required to load OpenCode conventions (see OpenCode Setup below)
• IntelliJ IDEA: While any IDE with Kotlin support works, working on Spockk specifications may be tricky, as the IDE support is only provided via the Spockk IntelliJ plugin

OpenCode Setup

Spockk uses OpenCode with the pshevche/opencode-conventions-config shared configuration.

Setup Steps

1. Fork and clone the repository:

   git clone https://github.com/YOUR-USERNAME/spockk.git
   cd spockk

2. Import the project into IntelliJ IDEA (Gradle configuration will be detected automatically)

Building and Testing

Build the project

./gradlew build

This compiles the code, runs all tests, and performs code quality checks.

Run tests

# Run all tests
./gradlew test

# Run tests for a specific module
./gradlew :spockk-compiler-plugin:test

Format code

The project uses Spotless with ktlint for code formatting:

# Check formatting
./gradlew spotlessCheck

# Apply formatting
./gradlew spotlessApply

Code style is enforced by .editorconfig (2-space indentation, LF line endings).

Testing the IntelliJ Plugin

To test your changes to the IntelliJ plugin:

1. Build the plugin:

   ./gradlew :spockk-intellij-plugin:build

2. Install in IntelliJ IDEA:

   • Navigate to Settings → Plugins → ⚙️ → Install Plugin from Disk
   • Select spockk-intellij-plugin/build/libs/spockk-intellij-plugin-<version>.jar
   • Restart IntelliJ IDEA

Submitting Changes

1. Create a feature branch:

   git checkout -b feature/my-feature

2. Make your changes and commit with clear messages

3. Ensure all checks pass:

   ./gradlew build

4. Push to your fork and open a Pull Request with:

   • A clear description of the changes
   • Reference to related issues (e.g., "Fixes #123")

Project Structure

• spockk-compiler-plugin: IR transformations for Kotlin compiler
• spockk-core: Kotlin-specific specification syntax
• spockk-gradle-plugin: Gradle plugin for applying the compiler plugin
• spockk-intellij-plugin: IntelliJ IDEA integration
• spockk-specs: Framework test specifications
• spockk-docs: User guide documentation

Resources

• User Guide
• Example Project