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 Parameters
 

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
@@ -48,6 +48,13 @@ NOTE: There are numerous configuration options for discovering and filtering tes
 test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full
 list of supported annotations and further details.
 
+.Duplicate test execution
+NOTE: Tests in a suite are executed in addition to the tests executed by every other test
+engine, so it is possible to for the same test to be executed twice. A common solution is
+to use a naming pattern. 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.
+
 ==== @BeforeSuite and @AfterSuite
 
 `@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a

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,12 @@
  * 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, so it is possible to for the same test to be executed twice. A
+ * common solution is to use a naming pattern. 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