It is the desire of the Jakarta EE specification projects to be able to make backwards incompatible changes to new versions of Jakarta EE specifications. The goal of this document is to enable that outcome while also providing guidance so that users can be aware of when backwards incompatible changes have occurred. The high-level framework in which this document is written:
It should be noted that this is a departure from the backwards compatibility guarantee previously offered by Java EE.
This process covers the Platform specification, its profiles, and the Component specifications that constitute them. Because of the capability for Component specifications to potentially release at a quicker cadence to the Platform and its profiles, it should be clarified that the Platform specification and its profiles are not allowed to “jump” a Component specification release to introduce breaking changes without first deprecating the feature/behaviour in the Platform specification and its profiles. This is to discourage a Component specification quickly doing two or more back-to-back releases to quickly remove a feature. See the Platform Feature section for further details.
We define four “realms” for changes. For clarity, “changes” here refers to additions (new methods to existing interfaces, and new interfaces), and removals (removing methods from existing interfaces, and removing interfaces entirely). The four realms for changes are:
isParmetersProvided from Expression Language.Backwards incompatible changes are allowed, but their introduction should be done in a controlled manner. All specifications should aim to use a versioning strategy conforming to the following pattern: Major.Minor.Patch
For the cases where backwards incompatible changes are being made, we follow a deprecation process that broadly has two steps:
The usage of tools such as BND to highlight when backwards incompatible changes are being used is encouraged. The implementation of these changes and deprecations and how this aligns to version changes depends on the realm in question. The broad overview however is:
The goal of this convention is to communicate to users when changes do or do not impact compatibility of their existing code. While not prohibited, declaration of a new major version without incompatible changes must be properly justified and documented in the Release Plan and project page. It should be anticipated that users will presume incompatibility across major version changes, regardless of attempts to document and/or justify the actual compatibility of the release. Therefore, this practice is discouraged.
API changes must conform to the following convention:
API methods that are marked for deprecation should be annotated with @Deprecated, and where possible the JavaDoc for the method should be updated to point users towards the replacement (if there is one). This mandates a minor version increment.
When making a change to existing behaviour (e.g. changing a default value), where possible a portable means to swap between the old and new behaviour should be introduced. The old behaviour must be the default.
The ability to swap between the behaviours must be determined by the specification. This ability can be removed in a major version.
If it is not reasonable to introduce a portable means to swap between the behaviour, the behaviour change can be made without it but this will require a major version change.
To summarise:
As noted above, the “deprecation” of behaviour by changing it to something else can happen in two ways:
Changes to Component features follow this versioning strategy:
Component features must be “deprecated” via a process similar to the Pruning process that existed before. A mandatory Component Feature is transitioned to being an optional feature in release N of the Component specification, and the optional feature should be marked as “Deprecated” in some manner (for example in a “Proposed for Removal” section of the specification). The optional feature may then be removed from the Component specification in release N+1 (or beyond). As noted above, the transition of the feature to being optional would mandate a major release, and the removal of it would mandate a subsequent major release.
An existing optional feature which has not yet been marked for deprecation must be marked as deprecated in a minor or major release, to then be removed in a subsequent major release.
It should be stressed that optional features do not have to be removed – the Component specification can maintain them as optional for as long as desired.
See the Platform Feature section for more details on how Component Features which are pruned in this manner are dealt with there.
The versioning strategy for the Platform and its profiles has in effect a marching major version regardless of backwards incompatible changes. This means it does not need to apply for an exception or provide justification that it intends to do a major version increment without a backwards incompatible change; it would only require to do so if it was planning a release without any of the criteria that would normally indicate a major version change (e.g. only changing the supported Java versions).
The Platform specification and its profiles use the following versioning strategy:
Deprecation from a Platform specification stance has two scopes:
Component specifications may be removed from the Platform specification via a similar manner to the original Pruning strategy, but with updates to reflect that the Platform specification no longer defines optional specifications or features (everything is either mandatory or not included). The deprecation strategy now would be:
When a Component feature is transitioned from being mandatory to optional, the Platform specification and its profiles must include a version of the specification which maintains this change for at least one release. Before an optional feature can be removed from the Platform specification, it must be marked for at least one release under a “Proposed for Removal” section. When removing an optional feature from the Platform specification or its profiles a reference must be provided to the version of the specification that marked the feature as “Proposed for Removal”.
It should be noted that the Platform specification and its profiles are not allowed to “jump” a release to introduce breaking changes without applying for an exception This is to discourage a component specification quickly doing two or more back-to-back releases to quickly remove a feature.
The intent is that there must be a release of the Platform specification which contains the feature in a “Proposed for Removal” state before it can be removed, but this should not necessarily prevent a component specification from moving at a quicker pace than that of the Platform.
For an example scenario:
Note that if the optional feature is maintained within the Component specification for more than one release (for example, if there was a 3.1 release of the Component specification that still contained the optional feature as per the example above), Platform specification release X+2 can include Component specification release 3.1 without having to include the optional feature. The same is true if Component specification release 4.0 did not remove the optional feature.