| [jakarta.ee-spec.committee] Versioning and Deprecations |
|
Hi, Following up on what was brought up towards the tail end of the call on Wednesday to (hopefully) keep the discussion going, a few comments were added to the document suggesting that my proposal around versioning and deprecations on behavioural
changes needs some work. For clarity, this bit: ------- When making a change to existing behaviour (e.g. changing a default value), a flag should be introduced to be able to swap between the old and new behaviour.
What the flag is need not be determined by the specification: it can be left up to the vendor implementations. The flag can be removed in the next major version. If it is not possible to introduce a flag to swap between the behaviour, the behaviour change can be made without the flag but this will require a major version change. To summarise: Major version increments: Backwards incompatible changes to behaviour, covering changes to existing behaviour without a flag to swap between the old and new behaviour, or the removal of a flag to support the old behaviour. Minor version increments: Brand new behaviour, or a change to existing behaviour with a flag to swap to the new behaviour. Patch version increments: Bug fixes. This covers cases where the feature is not working as intended – it doesn’t conform to what the specification dictates. Deprecation As noted above, the “deprecation” of behaviour by changing it to something else can happen in two ways: With a flag to switch from the old to the new behaviour in a minor release. The flag and support for the old behaviour can be dropped in a later major release Without a flag to switch between the old and new behaviour in a major release. This should be avoided where possible to avoid sudden breaking changes. ------- “Behaviour” here is referring to essentially all changes to “how something works”, with me picking as an example CDI changing the default bean discovery method. To explain what I was originally aiming for here, I was attempting to come up with a solution to the fact that you can’t annotate behaviour with @Deprecated – the only method we currently have for communicating deprecation or backwards
incompatible behavioural changes is to mention as such on the “Removals, deprecations or backwards incompatible changes” section on the
specification page. I was angling to mimic the stated aim of “deprecate in release N, remove in release N+1 or later” by introducing these flags (inspired by what CDI did – defining that a flag must be present to switch from the new behaviour back to the old).
I originally had it worded such that the specification could decide which way the flag should work (flag to switch from new to old vs. old to new), but I’ve accepted some suggestions that now mean it is defined that the flag always activates
the new behaviour. This allows a user to migrate to the new behaviour without having to wait for the “cliff drop” change of the old behaviour being removed in a subsequent release. The second comment (and the main impetus for me kicking off this discussion) is to do with major version increments: “Behaviour changes are backward incompatible changes no matter there is a flag to swap or not”. I’m not sure I agree with this – I lean more towards it only being backwards incompatible if there is no way to use the old behaviour. If the capability to use the old behaviour is present but the addition of activatable new behaviour constitutes
a major version increment doesn’t this mean that the only way to “deprecate” and finally change behaviour is by doing two major version releases? What are people’s thoughts on this? Thanks,
|
