This is a quick follow-up on the discussion re the meaning of deprecated back on the lucee support list a while ago.
I’d like to propose the following categorisation for the future:
Normal (no category): this is a normal feature and we think it’s good and appropriate to be used in the language.
Avoid: We think this is not the best way of doing something, but hey - if you think or feel you need to, go ahead.
Deprecated: Avoid + this might (or might not) be removed of the language at any future version (or replace “any” with “in 2+ versions from now” etc.). Also there’s no active development going into this function or feature anymore.
Hidden/Removed: Deprecated + it might still exist in code (or not), but it’s certainly removed from the docs and will be removed from code at some point. If you use this - tough luck.
Note: the new thing I’m proposing with this is “Avoid”. It caters for a very specific scenario in which we have (or want to) deal with 3 or so different CFML engines and want to keep compatibility options open without having to use “deprecated” (which is often understood as: this will be removed).
For instance CreateObject could be set to “Avoid” in the CFML dialect in Lucee 5. That means it’s not deprecated but we still express our opinion that CreateObject is a stupid function from a conceptual point of view and that we really think there are better ways of doing this.
And yes: all my suggestion does is introducing a nuance between Avoid and Deprecated, but I think it’s a valuable nuance.
The biggest missunderstanding we had with this is the interpretation of “deprecation”, the meaning of this status.
My understanding was for sure different, as it was or is for other, i understand it as “dislike” or “refuse”. For me to “depecate” something had abolutey nothing to do with “we will remove this after x releases”, it was only “we dislike this functinality and we encourage you not to use it”.
Important here is the status “hidden”, most people was not aware of this status, so maybe because of that they saw “deprecate” somewhere between deprecate and hidden.
So what if we would ditch “deprecate” and use indtead use an other term.
approve
disaprove
hidden
I’m not an english expert and i’m sure there could be better words, my point is that the problem is that the word “deprecate” is prejudiced and that we have 3 stati and not only 2. so im not sure if the best solution is to add a 4th stati.
if we are clear on the meaning of “deprecate” and maybe also need an other name it is not necessary to add a 4th stati.
IN my opinion adding a 4th stati makes it more complicated.
So how do you articulate things that you actually do mean “we will remove this after x releases”, which is a completely legitimate status to want to indicate?
You can use any terms you like provided you document what they mean. This was the only problem with the whole “deprecation” discussion… you were leaving it up to everyone to guess which particular variation of the term you were meaning. Just document it. Job done.
Obviously if you run with Kai’s idea, all that stuff will need to be documented too.
@agentK were you basing your list of terms on an established precedent from (an)other language(s)? Or just that seemed entirely reasonable terms to use?
That would indeed at least remove confusion — however it would regardless have to be defined what the certain states mean.
You’re right in saying that a 4th status does make things more complicated. However - if we were to leave it at the current 3 states (and renaming them as above) the issue would be that you’re also not having a certain piece of semantics: “This is going to be hidden in x versions”.
i completely agree that the current situation is not good, i simply try to find the best solution for it. @agentK solution is a very good one, i just want to find out if it is the best one. so it is not about convience me, it is about squeeze out the best solution.
“…Before implementing this, raise it within LAS for final say…”
Can you (or @modius or @micstriit) please elaborate a bit on what the process for getting “approval” on this does look like? Does it need a member vote? A board meeting? An informal email? @micstriit’s and/or @21Solutions approval?
I’m not sarcastic, but I’m honestly trying to understand what’s happening behind the closed doors.
A quick chat in Slack in this case (I think we’re mostly in agreement and don’t feel the need to formalize a vote on this particular issue as it won’t affect the language itself, just how the documentation is presented).
It will be interesting to see if, when process matures, whether issues such as this will warrant going through said process - or whether a quick chat suffices.
Edit (afterthought): From discussions that I’ve had, people within LAS are keen not to need to have LAS voting on issues unless necessary. Members genuinely share the same opinions as non-members on this I think. Getting formal process in place is high on the agenda, especially for language decisions and transparency is key. Its not where it needs to be right now.
A full explanation will have to wait till we have finalised our formal process around this, but in a bid to keep the conspiracies at bay…
The process in bullet points:
the development team (headed up by @micstriit) reviews issues/features that require development
work is scheduled; LAS has some input into priorities
anything deemed to be controversial is distributed to the wider community via the mailing list, or more recently here
anything that does not have a clear conclusion publicly is referred to the tech advisory board (still being organised)
anything that requires significant investment from LAS, or has no clear TAB resolution, may be referred to a LAS Member vote at the discretion of the LAS Management Board
For any reasonably clear suggestion all that is needed is a sanity check from the development team; these are the people who will literally put the code into the engine. Then the issue needs to be scheduled for work – there is only so much work that can be done so we need to have realistic expectations for how and when a resolution will come into effect.
Your suggestion of a tautological addition of Avoid is far from clear cut. Personally I think its not appropriate. This is a documentation issue and no amount of misinterpretation of the java definition of Deprecated will fix that fact.
Whether an issue is flagged as Avoid or Deprecate, every developer is going to want to look and see why they should be cautious of using the feature. That documentation would need to include; why something has been deprecated/avoided, whether or not there is an expectation of removal, and what the preferred alternative feature would be.
Given that you would need to refer to the documentation in every event, what possible advantage is there for having two types of “deprecated”? Surely there are a lot more types of “deprecated”; for example, discontinued with alternative, discontinued without alternative, discontinued but will remain for ever due to backward compatibility, and so on.
There’s been a single instance that i can think of where Avoid may have removed some people’s “confusion” – the deprecation of createObject(). Is it worth implementing a new status for this outlier? Or are there a number of examples where you think this status flag would apply?
Thanks, both @dom_watson and @modius, very clear and useful explanation.
This (and other content created as part of the various discussions) should be taken out of here and put on some public wiki pages or the Lucee website etc… to explain to others how LAS wants to and does work. Simple as that.
This is not about conspiracy, this (again) is about the openness and transparency LAS as an organisation is promoting itself as. Nothing else.
This is a good point. My initial thoughts when thinking about how this would be implemented in the documentation was having an editable deprecation description aside from the general description (to allow us to format it distinctly). Simply flagging something as deprecated, or “to avoid”, is probably not good enough (and will stoke flames).
For any deprecation, there would want to be a brief justification, links to the alternatives and links to any articles expanding on the new direction.
Would that be better than various deprecation statuses?
Edit: adding example
Something along these lines, but with distinct “Deprecated” formatting:
Yes, @modius has a valid point in there being the need to provide additional information for both “avoid” and “deprecated” anyway. And I think it needs to be visually clear and easy to find - similar to what @dom_watson has posted.
Re the question if having this additional explanation voiding the need for the “avoid” status — I’m not sure. Need to think about and mull over it a bit. Will report back in a day or two.
)