Add note about duplicate test execution with @Suite

CONTRIBUTING.md

@@ -177,8 +177,8 @@ To deprecate an item:
 
 ## Building the Project
 
-Please refer to [the readme](README.md#building-from-source) for the most common
-build commands.
+Please refer to [the readme](README.md#building-from-source) and [the documentation readme](documentation/README.md) for
+the most common build commands.
 
 ### Build Cache
 

documentation/README.md

@@ -18,7 +18,7 @@ This following Gradle command generates the HTML version of the User Guide as
 `build/docs/asciidoc/user-guide/index.html`.
 
 ```
-gradlew asciidoctor
+./gradlew asciidoctor
 ```
 
 On Linux operating systems, the `graphviz` package providing `/usr/bin/dot` must be
@@ -30,5 +30,5 @@ This following Gradle command generates the PDF version of the User Guide to
 `build/docs/asciidocPdf/user-guide/index.pdf`.
 
 ```
-gradlew asciidoctorPdf
+./gradlew asciidoctorPdf
 ```

documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc

@@ -1,8 +1,8 @@
 [[junit-platform-suite-engine]]
 === JUnit Platform Suite Engine
 
-The JUnit Platform supports the declarative definition and execution of suites of tests
-from _any_ test engine using the JUnit Platform.
+The Suite Engine supports the declarative selection and execution of tests from
+_any_ test engine using the JUnit Platform.
 
 [[junit-platform-suite-engine-setup]]
 ==== Setup
@@ -31,6 +31,18 @@ on `junit-platform-suite-api` and `junit-platform-suite-engine`.
 * `junit-platform-commons` in _test_ scope
 * `opentest4j` in _test_ scope
 
+[[junit-platform-suite-engine-setup-duplicate-test-execution]]
+===== Duplicate test execution
+
+Tests in a suite are executed in addition to the tests executed by every other test
+engine. This can result in the same tests being executed twice.
+
+This can be prevented by configuring your build tool to only include the
+`junit-platform-suite` engine. Or by using a naming pattern. For example name all suites
+`*Suite` and all tests `*Test` and configure your build tool to only include the former.
+
+Alternatively, consider <<running-tests-tags, using tags>> to select specific groups of tests.
+
 [[junit-platform-suite-engine-example]]
 ==== @Suite Example
 

junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java

@@ -26,7 +26,7 @@
  * {@code @Suite} marks a class as a test suite on the JUnit Platform.
  *
  * <p>Selector and filter annotations are used to control the contents of the
- * suite. Additionally configuration can be passed to the suite via the
+ * suite. Additionally, configuration can be passed to the suite via the
  * configuration annotations.
  *
  * <p>When the {@link IncludeClassNamePatterns @IncludeClassNamePatterns}
@@ -44,6 +44,13 @@
  * annotation disables the latter as a source of parameters so that only explicit
  * configuration parameters are taken into account.
  *
+ * <p>Note: Tests in a suite are executed in addition to the tests executed by every
+ * other test engine. This can result in the same tests being executed twice. This can be
+ * prevented by configuring your build tool to only include the Suite Engine. Or by
+ * using a naming pattern. For example name all suites {@code *Suite} and all tests
+ * {@code *Test} and configure your build tool to only include the former. Alternatively,
+ * consider using tags to select specific groups of tests.
+ *
  * @since 1.8
  * @see Select
  * @see SelectClasses