Stream: implementers
Topic: Determining if an attribute has been deprecated
Kevin Olbrich (Oct 01 2018 at 20:05):
Is there a simple way to determine if a particular attribute on a Resource has been deprecated and will be removed in a future version?
Kevin Olbrich (Oct 01 2018 at 20:08):
Something like a deprecated flag in the documentation would be helpful.
Michael Donnelly (Oct 01 2018 at 20:14):
Good point. I don't think we discussed how to actually flag things that have been deprecated.
Michel Rutten (Oct 01 2018 at 20:22):
http://build.fhir.org/versions.html#std-process
Michael Donnelly (Oct 01 2018 at 20:27):
Looks like the description is the same as for Informative?
Michel Rutten (Oct 01 2018 at 20:32):
Indeed LOL
Michel Rutten (Oct 01 2018 at 20:34):
IIRC we talked a bit about deprecation during a discussion about FHIR release versioning (in Cologne?)
Michel Rutten (Oct 01 2018 at 20:35):
Some more details here: http://build.fhir.org/versions.html#deprecation
Kevin Olbrich (Oct 01 2018 at 20:36):
What I'm thinking of is a scenario like this... There's a resource with an attribute we don't want to use anymore Resource.foo. One way to manage getting rid of this attribute would be to flag foo as deprecated in the next minor version and then delete it completely in the next one after that. This way in 3.8.0 we might label Resource.foo as deprecated and it would be dropped in 3.9.0. When it's marked that way in the documentation it gives folks a chance to alter their usage without needing to keep up with the tracker.
Dennis Patterson (Oct 01 2018 at 20:43):
Yes we discussed https://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=17214 in Cologne. While I think there was discussion on saying what version a deprecated item would be dropped, the conversation steered more towards duration (current indicates as 2 years per Michel's link). @Lloyd McKenzie may recall the details
Kevin Olbrich (Oct 01 2018 at 20:45):
What's the reasoning behind 2 years instead of the next major version?
Michael Donnelly (Oct 01 2018 at 21:56):
IIRC it's deprecated in the next major version and can't be removed entirely for at least two years after that.
Lloyd McKenzie (Oct 01 2018 at 22:06):
We may move to faster cycle than every 18-24 months once most things are normative. Specifying a time period rather than a number of releases was a better way of meeting the objective of "try to ensure time to migrate/plan to adapt"
Lloyd McKenzie (Oct 01 2018 at 22:11):
We didn't specify how we'd differentiate deprecated and retired content. However, we've committed to adding an extension to indicate when content became normative. I presume we'll follow the same pattern for the others. @Grahame Grieve ?
Grahame Grieve (Oct 01 2018 at 22:33):
we have one deprecated element: OperationOutcome.issue.location
Lloyd McKenzie (Oct 01 2018 at 23:14):
And no computable way of exposing that fact at present it looks like @Grahame Grieve ?
Grahame Grieve (Oct 01 2018 at 23:27):
I'm just debugging - it used to be
Grahame Grieve (Oct 01 2018 at 23:45):
<extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status"> <valueString value="Deprecated"/> </extension>
Lloyd McKenzie (Oct 02 2018 at 01:30):
valueString and not valueCode?
Lloyd McKenzie (Oct 02 2018 at 01:31):
(Would much prefer the latter...)
Brian Postlethwaite (Oct 02 2018 at 03:01):
I was planning on updating the .net FHIR client code generator to use this to add the code attribute to help developers know what is going on. (and also the hide the property from the intelisense too)
Lloyd McKenzie (Oct 02 2018 at 12:28):
I wouldn't necessarily hide it on deprecated - but might on retired. Best would be raise a compile warning for deprecated stuff
Michael Donnelly (Oct 02 2018 at 12:31):
I would definitely hide it from intellisense. The idea of deprecation is that we don't want anyone new to use it.
Robert McClure (Oct 02 2018 at 13:18):
@Michael Donnelly DEPRECATED should be used for elements that are in the process of being replaced by newer ones. IE, you don't hide these items as they are in current use, but you are giving notice that they will be retired in the future. RETIRED should be used when the element is no longer available for use at all. Is that how you are using the phrase?
Michael Donnelly (Oct 02 2018 at 13:25):
They aren't necessarily being replaced. As we defined it (I'll hunt down the tracker in a minute), when we deprecate an element, servers are still supposed to support it, but we'd rather clients didn't use it any more. Clients already using that element aren't required to change, but new ones ought not start using it.
Michael Donnelly (Oct 02 2018 at 13:27):
So a deprecated element should be in the spec (but marked as deprecated) so people understand what's being used currently. But I don't think a deprecated element should be in Intellisense, because we don't want someone writing new code to have that deprecated element appear.
Michael Donnelly (Oct 02 2018 at 13:35):
Here's the tracker from the last WGM where we added the concept of deprecation: https://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=17214
Kevin Olbrich (Oct 02 2018 at 13:36):
My concern around this was mostly in discoverability. I want there to be mechanisms in place to alert developers that it's been deprecated and thus should not be used. Adding flags to attributes and/or extensions would allow tooling to know this, and the documentation should clearly indicate when it will be removed and what to use instead (when appropriate). @Michael Donnelly what does your IDE do when you try to use a deprecated method in other languages? That might be a good model for how to handle this.
Michel Rutten (Oct 02 2018 at 13:39):
.NET provides an Obsolete attribute that generates warnings in the IDE.
Michel Rutten (Oct 02 2018 at 13:40):
We already use this in the .NET API to indicate deprecated classes and methods.
Michael Donnelly (Oct 02 2018 at 13:45):
We use .NET too, so @Michel Rutten beat me to it. :)
Brian Postlethwaite (Oct 03 2018 at 02:02):
Yep, all of this.
If at some point we get more serious than deprecated, then the warning would become an error. But we're a long way from it today.
Brian Postlethwaite (Oct 03 2018 at 02:02):
(Sounds like I have support to do what I was going to do)
Michael Donnelly (Oct 03 2018 at 14:14):
It looks like the descriptive text for Deprecated in 2.7.0.1 The Standards Development Process is copied from the line above. I made a tracker for this with proposed wording: https://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=19280
Last updated: Apr 12 2022 at 19:14 UTC
