Polish CONTRIBUTING.md

CONTRIBUTING.md

@@ -28,10 +28,10 @@ Issue: #999
 ## Pull Requests
 
 Our [Definition of Done](https://github.com/junit-team/junit5/wiki/Definition-of-Done)
-offers some guidelines on what we expect from a pull request.
+(DoD) offers some guidelines on what we expect from a pull request.
 Feel free to open a pull request that does not fulfill all criteria, e.g. to discuss
 a certain change before polishing it, but please be aware that we will only merge it
-in case the DoD is met.
+once the DoD is met.
 
 Please add the following lines to your pull request description:
 
@@ -95,16 +95,15 @@ code -- class names, method names, variable names, etc.
 ### Javadoc
 
 - Javadoc comments should be wrapped after 80 characters whenever possible.
-- This first paragraph must be a single, concise sentence that ends with a period (".").
-- Place `<p>` on the same line as the first line in a new paragraph and precede `<p>` with a blank line.
+- This first paragraph must be a single, concise sentence that ends with a period (`.`).
+- Place `<p>` on the same line as the first line of a new paragraph and precede `<p>` with a blank line.
 - Insert a blank line before at-clauses/tags.
 - Favor `{@code foo}` over `<code>foo</code>`.
 - Favor literals (e.g., `{@literal @}`) over HTML entities.
-- New classes and methods should have `@since ...` annotation.
-- Use `@since 5.0` instead of `@since 5.0.0`.
-- Do not use `@author` tags. Instead, contributors are listed on [GitHub](https://github.com/junit-team/junit5/graphs/contributors).
-- Do not use verbs in third person form (e.g. use "Discover tests..." instead of "Discovers tests...")
-  in the first sentence describing a method.
+- New classes and methods should declare a `@since ...` tag.
+- Use `@since 5.10` instead of `@since 5.10.0`.
+- Do not use `@author` tags. Instead, contributors are listed on the [GitHub](https://github.com/junit-team/junit5/graphs/contributors) page.
+- Do not use verbs in third-person form in the first sentence of the Javadoc for a method -- for example, use "Discover tests..." instead of "Discovers tests...".
 
 #### Examples
 
@@ -121,11 +120,11 @@ See [`ExtensionContext`](junit-jupiter-api/src/main/java/org/junit/jupiter/api/e
 
 #### Assertions
 
-- Use `org.junit.jupiter.api.Assertions` wherever possible.
+- Use `org.junit.jupiter.api.Assertions` for simple assertions.
 - Use AssertJ when richer assertions are needed.
 - Do not use `org.junit.Assert` or `junit.framework.Assert`.
 
-#### Mocking
+#### Mocking and Stubbing
 
 - Use either [Mockito](https://github.com/mockito/mockito) or hand-written test doubles.
 
@@ -143,10 +142,11 @@ See [`ExtensionContext`](junit-jupiter-api/src/main/java/org/junit/jupiter/api/e
 
 ### Deprecation
 
-Publicly available interfaces, classes and methods have a defined lifecycle
+The JUnit 5 project uses the `@API` annotation from [API Guardian](https://github.com/apiguardian-team/apiguardian).
+Publicly available interfaces, classes, and methods have a defined lifecycle
 which is described in detail in the [User Guide](https://junit.org/junit5/docs/current/user-guide/#api-evolution).
-This process is using the `@API` annotation from [API Guardian](https://github.com/apiguardian-team/apiguardian).
-It also describes the deprecation process followed for API items.
+
+That following describes the deprecation process followed for API items.
 
 To deprecate an item:
 - Update the `@API.status` to `DEPRECATED`.