diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1bf0398848b..30daed148f8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -30,6 +30,52 @@ We provide [test case templates for all Hibernate projects](https://github.com/h
to help you get started:
just fork this repository, build your test case and attach it as an archive to a JIRA issue.
+## Setting up a development environment
+
+### Build tools
+
+You will need JDK 17 exactly for the build.
+
+A maven wrapper script is provided at the root of the repository (`./mvnw`),
+so you can use that and don't need to care about the required version of Maven
+(it will be downloaded automatically).
+
+### IDE
+
+#### IntelliJ IDEA
+
+Make sure you use IntelliJ IDEA 2022.1 or later, as previous versions have some
+[trouble with generated sources](https://youtrack.jetbrains.com/issue/IDEA-286455).
+
+You will need to change some settings:
+
+* `Build, Execution, Deployment > Build Tools > Maven`: set `Maven home path` to `Use Maven wrapper`
+* In `Project structure`, make sure the project JDK is JDK 17.
+* Set up [formatting rules and code style](#setup-ide-formatting).
+
+Then a few steps will initialize your workspace:
+
+* In the "Maven" side panel, click "Reload all Maven projects".
+* In the "Maven" side panel, click "Generate Sources and Update Folders For All Projects".
+ This will take a while.
+* To check your setup, click `Build > Rebuild Project`.
+ If this completes successfully, your workspace is correctly set up.
+
+#### Eclipse
+
+Eclipse shouldn't require any particular setup besides
+[formatting rules and code style](#setup-ide-formatting).
+
+#### Formatting rules and style conventions
+
+The Hibernate family projects share the same style conventions,
+and we provide settings for some IDEs to help you follow these conventions.
+See:
+
+* [here for IntelliJ IDEA](https://hibernate.org/community/contribute/intellij-idea/)
+* [here for Eclipse IDE](https://hibernate.org/community/contribute/eclipse-ide/)
+
+
## Contributing code
### Prerequisites
@@ -44,6 +90,18 @@ As discussed in the linked page, this also includes:
* [Setting](https://help.github.com/articles/set-up-git) up your local git install
* Cloning your fork
+### Development environment
+
+Make sure to [set up your development environment](#setup) correctly.
+
+Be especially careful about setting up the [formatting rules and code style](#setup-ide-formatting).
+
+If you built the project at least once (`./mvnw clean install`),
+you can very quickly check that you have respected the formatting rules by running Checkstyle:
+```bash
+./mvnw checkstyle:check -fn
+```
+
### Create a topic branch
Create a "topic" branch on which you will work. The convention is to name the branch
@@ -54,24 +112,10 @@ on the JIRA HSEARCH-123:
git checkout -b HSEARCH-123 main
```
-### Formatting rules and style conventions
-
-The Hibernate family projects share the same style conventions,
-and we provide settings for some IDEs to help you follow these conventions.
-See:
-
-* [here for IntelliJ IDEA](https://hibernate.org/community/contribute/intellij-idea/)
-* [here for Eclipse IDE](https://hibernate.org/community/contribute/eclipse-ide/)
-
-If you built the project at least once (`./mvnw clean install`),
-you can very quickly check that you have respected the formatting rules by running Checkstyle:
-```bash
-./mvnw checkstyle:check -fn
-```
-
### Code
-See the [README](README.md) for details about how to build the project and about the structure of the source code.
+See [this section](#source-code-structure) for details about the structure of the source code,
+and [this section](#building-from-source) for how to build the project.
If you need help, feel free to contact us, be it through comments on your JIRA ticket,
emails on the mailing list, or directly though our chat:
@@ -113,7 +157,7 @@ git pull --rebase upstream main
* Update the JIRA issue, using the "Link to pull request" button to include a link to
the created pull request.
-## Source code structure
+## Source code structure
The project is split in several Maven modules:
@@ -150,13 +194,11 @@ and transform it to use Hibernate ORM 6 instead of Hibernate ORM 5.x.
* `reports`: Module built last, producing reports related to test coverage in particular.
* `util`: Various modules containing util classes, both for runtime and for tests.
-## Building from source
+## Building from source
-### Basic build
+### Basic build from the commandline
-You will need JDK 17 exactly;
-newer JDKs will require you to [pass additional properties](#other-jdks)
-in order for tests to run correctly.
+First, make sure your [development environment is correctly set up](#setup).
The following command will build Hibernate Search, install it in your local Maven repository,
and run unit tests and integration tests.
@@ -192,6 +234,11 @@ To build the distribution bundle run:
### Other JDKs
+To test Hibernate Search against another JDK
+than [the one required for the build](#setup-build-tools),
+you will need to have both JDKs installed,
+and then you will need to pass additional properties to Maven.
+
To test Hibernate Search against JDK 8:
```bash
diff --git a/pom.xml b/pom.xml
index 48980a7dfbe..b4b850e14b5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -2552,6 +2552,10 @@
Here's the issue in the IDEA bug tracker: https://youtrack.jetbrains.com/issue/IDEA-85478
It's fixed in 2022.1 EAP 6, so hopefully we'll be able to get rid of this soon. -->
${java-version.test.release}
+
+ true