There are many ways to contribute to Spock:
-
Spreading the word by talking, tweeting, blogging, presenting, submitting talks, writing tutorials or articles (or a book!), sharing success stories, etc.
-
Helping other users by participating in gitter discussions, answering Spock questions on Stack Overflow, etc.
-
Providing early feedback on development snapshots and new features
-
Improving and extending the reference documentation (source)
-
Translating blog posts, articles, and the reference documentation to other languages (with permission of the authors)
-
Fixing open issues listed in the issue tracker
-
Proposing, discussing, and implementing new features
-
Donating money to fund further development
-
Surprising us with some other form of contribution!
All forms of contribution are very much appreciated.
Good communication makes a big difference. We are always eager to listen, reflect, and discuss. Don’t hesitate to get in touch via the issue tracker, discussions, or gitter. Choose whatever medium feels most appropriate.
You can triage issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to Spock on CodeTriage.
To contribute code or documentation, please submit a pull request to the GitHub repository.
A good way to familiarize yourself with the codebase and contribution process is to look for and tackle low-hanging fruits in the issue tracker. Before embarking on a more ambitious contribution, please quickly get in touch with us. This will help to make sure that the contribution is aligned with Spock’s overall direction and goals, and gives us a chance to guide design and implementation where needed.
We appreciate your effort, and want to avoid a situation where a contribution requires extensive rework (by you or by us), sits in the queue for a long time, or cannot be accepted at all!
When reviewing pull requests, we value the following qualities (in no particular order):
-
Carefully crafted, clean and concise code
-
Small, focused commits that tackle one thing at a time
-
New code blends in well with existing code, respecting established coding standards and practices
-
Tests are updated/added along with the code, communicate intent and cover important cases (see Tests for additional information)
-
Documentation (Javadoc, Groovydoc, reference documentation) is updated/added along with the code
-
A good commit message that follows the seven rules
Don’t be intimidated by these words. Pull requests that satisfy Spock’s overall direction and goals (see above), are crafted carefully, and aren’t aiming too high, have a good chance of getting accepted. Before doing so, we may ask for some concrete improvements to be made, in which case we hope for your cooperation.
The implementation language for the spock-core module is Java. Java is also the default language for all other modules (except spock-specs), but it’s fine to use Groovy when there is a concrete reason. As a general guideline, use the same language as the surrounding code.
Spock supports JRE 1.6 and higher. Therefore, language features and APIs that are only available in Java 1.7 or higher cannot be used. Exceptions to this rule need to be discussed beforehand. The same goes for changes to user-visible behavior.
All tests are written in Spock. Tests for spock-core are located in the spock-specs project; all other projects have co-located tests. For each user-visible behavior, a functional test is required. Functional tests for spock-core are located under spock-specs/src/test/groovy/org/spockframework/smoke.
Spock is built with Gradle. The only prerequisite for executing the build is an installation of JDK 8 and JDK 11. After cloning the GitHub repository, cd into the top directory and execute ./gradlew build (Windows: gradlew build). The build should succeed without any errors. gradlew tasks lists the available tasks. Always use the Gradle Wrapper (gradlew command) rather than your own Gradle installation.
Each push to the official GitHub repository triggers a Linux CI build and Windows CI build. Pull requests are built as well.
Using an IDE is recommended but not mandatory. Whether or not you use an IDE, please make sure that gradlew build succeeds before submitting a pull request.
The latest IntelliJ IDEA (Community Edition) is the preferred IDE for developing Spock. To generate an IDEA project configuration:
-
./gradlew cleanIdea idea, followed by -
File -> Openin Intellij, then -
select the appropriate
spock-2.5.ipr.
Note: You can provide an optional 'variant' flag to the gradle build -Dvariant=[2.5|3.0|4.0] that specifies the version of groovy you wish to use. For example, if we wish to use groovy 3.0, we would run ./gradlew cleanIdea idea -Dvariant=3.0 and import the generated spock-3.0.ipr into Intellij.
This should result in a fully functional IDE setup where:
-
Git VCS integration is configured
-
Important formatter settings are configured (e.g. two spaces indent)
-
Both Java and Groovy code compiles without problems
-
All tests can be run without problems
From time to time (e.g. when someone has added a new dependency), it may be necessary to resync the IDEA project with the Gradle build. This is done by rerunning the steps above.
Note: Unfortunately there are currently some issues with Intellij’s Gradle support that prevent integration with the Spock project. Please use the method described above rather than importing the top-level build.gradle file.
Eclipse 3.7+ with the latest Groovy plugin should work reasonably well for developing Spock. To import the Gradle build into Eclipse, either run gradlew eclipse and import the generated Eclipse projects via File->Import->General->Existing Project into Workspace, or install the Eclipse Gradle Tooling and import via File->Import->Gradle->Gradle Project. Either method should result in an IDE setup where:
-
Both Java and Groovy code compiles without problems
-
All tests can be run without problems
From time to time (e.g. when someone has added a new dependency), it may be necessary to resync the Eclipse project with the Gradle build. Depending on the method of import (see above), this is done by re-running gradlew [cleanEclipse] eclipse and then refreshing all Eclipse projects (F5), or by selecting Gradle->Refresh All in the Package Explorer’s context menu.
If you encounter any problems with the IDE setup, or want to make some improvements to it, please get in touch with us.