Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakarta.ee-spec.committee] Versioning and Deprecations

Hi all,

I’d like to start by thanking Andrew for spearheading this effort, it has got us talking which is a great thing. Here are my thoughts on some of the proposals:

  • Controlling behaviour via flags: I’m ok with that but, echoing David’s concerns, I think the flag should be part of the spec itself to ensure portability.
  • Default behaviour when flags are involved: if, in the absence of specifying a value for the flag, the default behaviour is to stick to the existing behaviour, I would call that a backwards-compatible change; if the default behaviour is the new behaviour, I would call that an backwards-incompatible change that requires a new major version. I appreciate it’s difficult to draw the line of where compatibility ends and incompatibility begins, so my thinking here is a bit mechanistic: I have nightly builds that try to upgrade dependencies automatically, it does this by uplifting the dependency and running the build. If the build passes, I call that “compatible” and save the configuration to use the new version; if the build fails, I call that “incompatible” and take note to investigate. It could be that, in order to turn the build from red back to green, all I need to do is add a flag that preserves previous behaviour, but the fact that I’ve gone through a red build tells me that this was a backwards-incompatible change, albeit one that was very easy to address.
  • Use of @Deprecated: I think this is orthogonal to the use of flags. There will be situations where the annotation makes sense but the flag doesn’t, or vice versa. There will also be situations where both can coexist, and in those instances I think this would be a nice way to combine what have been said so far:
    • Stage 1: add the @Deprecated annotation, and a flag that defaults to the existing behaviour. This way people have time to prepare for the change, but can also switch to the new behaviour straightaway if so they wish. This is a backwards compatible change that would require just a new minor version.
    • Stage 2: keep the @Deprecated annotation, but change the default behaviour of the flag to the new behaviour. This would be a backwards-incompatible change that would require a new major version.
    • Stage 3: remove the old behaviour, remove the flag, remove the @Deprecated annotation. By my own logic in my previous point this would be considered a backwards-incompatible change for it could cause a red nightly build (if someone has the flag currently configured to “previous behaviour”), so this would also need a new major version.

I’m conscious that requiring to major bumps might be a bit much so keen to know what people think at this point. Perhaps we can have two different processes depending on how sever the change is. For simple changes we can maybe dispense with the flag and merge Stage 2 and Stage 3, while for more complex ones we can have the full three stages.

Thoughts?
Abraham
 



On 1 Jul 2023, at 01:25, David Blevins <dblevins@xxxxxxxxxxxxx> wrote:

First, so great to see email discussion. 

How attached are people to this particular sentence?

   "What the flag is need not be determined by the specification: it can be left up to the vendor implementations.”

I might be in the minority, but I think the approach we took in CDI is an anti-pattern.  Something about taking a portable behavior and putting it behind a non-portable flag doesn’t sit well with me.

Maybe instead of encouraging vendor-specific flags we could basically advise spec teams to seek guidance from the Spec Committee if they don’t see a portable approach.

We wouldn’t be saying people can’t have vendor-specific flags for previously portable behavior, just that it’s generally discouraged and there should be a larger discussion first.  Those situations really need more eyes and ideas.

Thoughts?


On Jun 30, 2023, at 4:43 AM, Andrew Pielage <andrew.pielage@xxxxxxxxxxx> wrote:

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,
--
Andrew Pielage
Senior Software Engineer
 
<image004.png>
 
<image005.png>
+448005385490
Payara Services Ltd., Registered office: Malvern Hills Science Park, Geraldine Road, Malvern, WR14 3SZ, United Kingdom
Registered in England and Wales: 09998946 | VAT: GB 193854467
Payara is a proud recipient of the prestigious Queen's Award for Enterprise: International Trade 2021
 
_______________________________________________
jakarta.ee-spec.committee mailing list
jakarta.ee-spec.committee@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee

_______________________________________________
jakarta.ee-spec.committee mailing list
jakarta.ee-spec.committee@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee


Back to the top