File size: 2,955 Bytes
2795186 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
[[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.
|