|
|
[[api-evolution]] |
|
|
== API Evolution |
|
|
|
|
|
One of the major goals of JUnit 5 is to improve maintainers' capabilities to evolve JUnit |
|
|
despite its being used in many projects. With JUnit 4 a lot of stuff that was originally |
|
|
added as an internal construct only got used by external extension writers and tool |
|
|
builders. That made changing JUnit 4 especially difficult and sometimes impossible. |
|
|
|
|
|
That's why JUnit 5 introduces a defined lifecycle for all publicly available interfaces, |
|
|
classes, and methods. |
|
|
|
|
|
[[api-evolution-version-and-status]] |
|
|
=== API Version and Status |
|
|
|
|
|
Every published artifact has a version number `<major>.<minor>.<patch>`, and all publicly |
|
|
available interfaces, classes, and methods are annotated with {API} from the |
|
|
{API_Guardian} project. The annotation's `status` attribute can be assigned one of the |
|
|
following values. |
|
|
|
|
|
[cols="20,80"] |
|
|
|=== |
|
|
| Status | Description |
|
|
|
|
|
| `INTERNAL` | Must not be used by any code other than JUnit itself. Might be removed without prior notice. |
|
|
| `DEPRECATED` | Should no longer be used; might disappear in the next minor release. |
|
|
| `EXPERIMENTAL` | Intended for new, experimental features where we are looking for feedback. + |
|
|
Use this element with caution; it might be promoted to `MAINTAINED` or |
|
|
`STABLE` in the future, but might also be removed without prior notice, even in a patch. |
|
|
| `MAINTAINED` | Intended for features that will not be changed in a backwards- |
|
|
incompatible way for *at least* the next minor release of the current |
|
|
major version. If scheduled for removal, it will be demoted to `DEPRECATED` first. |
|
|
| `STABLE` | Intended for features that will not be changed in a backwards- |
|
|
incompatible way in the current major version (`5.*`). |
|
|
|=== |
|
|
|
|
|
If the `@API` annotation is present on a type, it is considered to be applicable for all |
|
|
public members of that type as well. A member is allowed to declare a different `status` |
|
|
value of lower stability. |
|
|
|
|
|
[[api-evolution-experimental-apis]] |
|
|
=== Experimental APIs |
|
|
|
|
|
The following table lists which APIs are currently designated as _experimental_ via |
|
|
`@API(status = EXPERIMENTAL)`. Caution should be taken when relying on such APIs. |
|
|
|
|
|
include::{experimentalApisTableFile}[] |
|
|
|
|
|
[[api-evolution-deprecated-apis]] |
|
|
=== Deprecated APIs |
|
|
|
|
|
The following table lists which APIs are currently designated as _deprecated_ via |
|
|
`@API(status = DEPRECATED)`. You should avoid using deprecated APIs whenever possible, |
|
|
since such APIs will likely be removed in an upcoming release. |
|
|
|
|
|
include::{deprecatedApisTableFile}[] |
|
|
|
|
|
[[api-evolution-tooling]] |
|
|
=== @API Tooling Support |
|
|
|
|
|
The {API_Guardian} project plans to provide tooling support for publishers and consumers |
|
|
of APIs annotated with {API}. For example, the tooling support will likely provide a |
|
|
means to check if JUnit APIs are being used in accordance with `@API` annotation |
|
|
declarations. |
|
|
|
