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:
...
Deprecation from a Platform specification stance has two scopes:
-
Removal of Component specifications
-
Removal of Component features
Component Specifications
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”.
Component Features
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.
Thanks,
|
-- |
Andrew
Pielage
Senior Software Engineer |
From: jakarta.ee-spec.committee <jakarta.ee-spec.committee-bounces@xxxxxxxxxxx> on behalf of Abraham Marin-Perez via jakarta.ee-spec.committee
<jakarta.ee-spec.committee@xxxxxxxxxxx>
Sent: 27 November 2024 18:16
To: Jakarta specification committee <jakarta.ee-spec.committee@xxxxxxxxxxx>
Cc: Abraham Marin-Perez <abraham.marin.perez@xxxxxxxxxx>
Subject: [jakarta.ee-spec.committee] Changing specs from Mandatory to Optional
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.
Thoughts?
Abraham
