> users need to change their expectations and prepare for the fact that a spec that was guaranteed to be there may not be there in the future
I don’t think this is users’ expectation.
The optional features are the result of compromises among vendors.
Some vendors think this feature is important, but some are not.
The optional features will continue to be in the specifications as long as some of vendors deem them important.
Users’ expectation is different from the one by deprecation.
-Kenji Kazumura
From: jakarta.ee-spec.committee <jakarta.ee-spec.committee-bounces@xxxxxxxxxxx>
On Behalf Of Thomas Watson via jakarta.ee-spec.committee
Sent: Monday, December 2, 2024 11:17 PM
To: Jakarta specification committee <jakarta.ee-spec.committee@xxxxxxxxxxx>
Cc: Thomas Watson <tjwatson@xxxxxxxxxx>
Subject: Re: [jakarta.ee-spec.committee] Changing specs from Mandatory to Optional
I agree with Andrew but want to reinforce the statements on individual specifications that are included in the platform or the profile specifications. The platform and
profile specification must not have any optional components. The individual specifications may have optional components within their own specifications, but once they are included in the platform or a profile specification then a decision must be made to
make that optional component of the individual specification mandatory or excluded the optional component from the platform or profile specification.
Making an entire individual specification optional will not have the desired effect for application developers using the platform or a profile specification because a
decision must be made by the platform specification on if the individual specification is included as mandatory or excluded altogether as its entire individual specification is optional. I don't see the value of making the complete individual specification
optional if the result is the complete specification is required to be included in the platform or a profile specification. Deprecation for removal is the way to go for informing application developers of our intent to remove a specification. Adding an additional
optional indicator will not help in my opinion.
So I've had a read of the existing process we have around this: https: //jakarta. ee/committees/specification/versioning/ It's a bit of a read, but
I think your proposal is already present for the Platform: for both component features or entire
It's a bit of a read, but I think your proposal is already present for the Platform: for both component features or entire specifications, the Platform
specification must have a release which marks it for pruning.
There isn't a safeguard as such for component specifications though, other than mandating that they perform a major release to transition a feature into
the optional state.
It has been a few years since I wrote it, but I believe this is intentional to not make it overly onerous to remove things from the Platform specification.
The relevant bits around things becoming optional (or optional becoming mandatory) are here:
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:
Component Feature changes – these are changes to the features defined in a Component specification (e.g. Jakarta Enterprise Beans). This realm covers
the addition and removal of features (mandatory or optional), as well as the transition of an existing mandatory feature to optional (or vice-versa).
-
An example would be if Enterprise Java Beans elected to fully remove Entity Beans from the specification (they are still an optional part of the EJB specification, but are excluded
from the Platform specification).
Platform Feature changes – these are changes to the Component specifications included in the Jakarta EE Platform specification and its profiles. This
covers the addition and removal of mandatory Component specifications, the inclusion or exclusion of optional Component features from mandatory Component specifications, and the inclusion or exclusion of entire Component specifications as optional.
-
An example would be the pruning of Entity Beans, being made optional in Jakarta EE 9, and removed in EE 10. Entity Beans still exist as an optional feature within the Enterprise Beans
4.0 Component specification which was used for both Jakarta EE Platform 9.1 & 10, but the Platform specification elected to remove the feature from EE10 (as in it didn’t include it)
Changes to Component features follow this versioning strategy:
-
Major version change - removal of an optional or mandatory feature, or the transition of an existing mandatory feature to being an optional one.
-
Minor version change – new features (mandatory or optional), or the transition of an existing optional feature to being a mandatory one.
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.
The Platform specification and its profiles use the following versioning strategy:
-
Major version changes contain one or more of the following:
-
One or more changes to the set of Component specifications included in the previous version
-
One or more changes to the set of optional Component features included in the previous version.
Deprecation from a Platform specification stance has two scopes:
-
Removal of Component specifications
-
Removal of Component features
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:
-
Specification is marked for pruning in release N. This is done by explicitly marking the specification under a “Proposed for Removal” section.
-
The specification is removed from the Platform specification in release N+1 (or beyond). When doing so a reference must be given to the version of the Platform specification that
marked it as “Proposed for Removal”.
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.
|
--
|
|
Andrew
Pielage
Senior Software Engineer
|
Hi team,
Following up from the conversation during today’s Spec Committee call, I'd like to propose that we specify a process for changing specs from Mandatory to Optional that is analogous to the deprecation process. The rationale
for this is that, when changing specs from Mandatory to Optional, users need to change their expectations and prepare for the fact that a spec that was guaranteed to be there may not be there in the future; in essence, this is similar to setting expectations
for features/specs/components that are marked for deprecation and removed.
I propose a similar process: a spec that is going from Mandatory to Optional must first be marked as “candidate for optional”, and can then be made Optional not sooner than one major version later.
|
