#2914: explain 'superseding' for lifecycle methods in user guide

Author: mmerdes

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -799,27 +799,31 @@ callbacks implemented by `Extension2`. `Extension1` is therefore said to _wrap_
 JUnit Jupiter also guarantees _wrapping_ behavior within class and interface hierarchies
 for user-supplied _lifecycle methods_ (see <<writing-tests-classes-and-methods>>).
 
-* `@BeforeAll` methods are inherited from superclasses as long as they are not _hidden_ or
-  _overridden_. Furthermore, `@BeforeAll` methods from superclasses will be executed
-  **before** `@BeforeAll` methods in subclasses.
+* `@BeforeAll` methods are inherited from superclasses as long as they are not _hidden_, or
+  _overridden_, or _superseded_ (i.e., replaced based on signature only, irrespective of
+  Java's visibility rules). Furthermore, `@BeforeAll` methods from superclasses will be
+  executed **before** `@BeforeAll` methods in subclasses.
 ** Similarly, `@BeforeAll` methods declared in an interface are inherited as long as they
    are not _hidden_ or _overridden_, and `@BeforeAll` methods from an interface will be
    executed **before** `@BeforeAll` methods in the class that implements the interface.
-* `@AfterAll` methods are inherited from superclasses as long as they are not _hidden_ or
-  _overridden_. Furthermore, `@AfterAll` methods from superclasses will be executed
-  **after** `@AfterAll` methods in subclasses.
+* `@AfterAll` methods are inherited from superclasses as long as they are not _hidden_, or
+  _overridden_, or _superseded_ (i.e., replaced based on signature only, irrespective of
+  Java's visibility rules). Furthermore, `@AfterAll` methods from superclasses will be
+  executed **after** `@AfterAll` methods in subclasses.
 ** Similarly, `@AfterAll` methods declared in an interface are inherited as long as they
    are not _hidden_ or _overridden_, and `@AfterAll` methods from an interface will be
    executed **after** `@AfterAll` methods in the class that implements the interface.
 * `@BeforeEach` methods are inherited from superclasses as long as they are not
-  _overridden_. Furthermore, `@BeforeEach` methods from superclasses will be executed
-  **before** `@BeforeEach` methods in subclasses.
+  _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of
+  Java's visibility rules). Furthermore, `@BeforeEach` methods from superclasses will be
+  executed **before** `@BeforeEach` methods in subclasses.
 ** Similarly, `@BeforeEach` methods declared as interface default methods are inherited as
    long as they are not _overridden_, and `@BeforeEach` default methods will be executed
    **before** `@BeforeEach` methods in the class that implements the interface.
 * `@AfterEach` methods are inherited from superclasses as long as they are not
-  _overridden_. Furthermore, `@AfterEach` methods from superclasses will be executed
-  **after** `@AfterEach` methods in subclasses.
+  _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of
+  Java's visibility rules). Furthermore, `@AfterEach` methods from superclasses will be
+  executed **after** `@AfterEach` methods in subclasses.
 ** Similarly, `@AfterEach` methods declared as interface default methods are inherited as
    long as they are not _overridden_, and `@AfterEach` default methods will be executed
    **after** `@AfterEach` methods in the class that implements the interface.

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -34,10 +34,10 @@ in the `junit-jupiter-api` module.
 | `@TestInstance`          | Used to configure the <<writing-tests-test-instance-lifecycle, test instance lifecycle>> for the annotated test class. Such annotations are _inherited_.
 | `@DisplayName`           | Declares a custom <<writing-tests-display-names,display name>> for the test class or test method. Such annotations are not _inherited_.
 | `@DisplayNameGeneration` | Declares a custom <<writing-tests-display-name-generator,display name generator>> for the test class. Such annotations are _inherited_.
-| `@BeforeEach`            | Denotes that the annotated method should be executed _before_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@Before`. Such methods are _inherited_ unless they are _overridden_.
-| `@AfterEach`             | Denotes that the annotated method should be executed _after_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@After`. Such methods are _inherited_ unless they are _overridden_.
-| `@BeforeAll`             | Denotes that the annotated method should be executed _before_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@BeforeClass`. Such methods are _inherited_ (unless they are _hidden_ or _overridden_) and must be `static` (unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used).
-| `@AfterAll`              | Denotes that the annotated method should be executed _after_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@AfterClass`. Such methods are _inherited_ (unless they are _hidden_ or _overridden_) and must be `static` (unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used).
+| `@BeforeEach`            | Denotes that the annotated method should be executed _before_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@Before`. Such methods are _inherited_ unless they are _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules).
+| `@AfterEach`             | Denotes that the annotated method should be executed _after_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@After`. Such methods are _inherited_ unless they are _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules).
+| `@BeforeAll`             | Denotes that the annotated method should be executed _before_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@BeforeClass`. Such methods are _inherited_ (unless they are _hidden_, or _overridden_, or _superseded_, i.e., replaced based on signature only, irrespective of Java's visibility rules) and must be `static` (unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used).
+| `@AfterAll`              | Denotes that the annotated method should be executed _after_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@AfterClass`. Such methods are _inherited_ (unless they are _hidden_, or _overridden_, or _superseded_, i.e., replaced based on signature only, irrespective of Java's visibility rules) and must be `static` (unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used).
 | `@Nested`                | Denotes that the annotated class is a non-static <<writing-tests-nested,nested test class>>. On Java 8 through Java 15, `@BeforeAll` and `@AfterAll` methods cannot be used directly in a `@Nested` test class unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used. Beginning with Java 16, `@BeforeAll` and `@AfterAll` methods can be declared as `static` in a `@Nested` test class with either test instance lifecycle mode. Such annotations are not _inherited_.
 | `@Tag`                   | Used to declare <<writing-tests-tagging-and-filtering,tags for filtering tests>>, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are _inherited_ at the class level but not at the method level.
 | `@Disabled`              | Used to <<writing-tests-disabling,disable>> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not _inherited_.