Strategy on handling obsoleted/deprecated classes

[modelica-trac-importer]

Modified by dietmarw on 3 Oct 2014 07:42 UTC
Currently the MSL contains almost 90 classes marked as obsolete/deprecated and with a notice that they will be removed soon.

Now in my 9 years of following the MSL development I can not recall an actual removal having happened even once. So the question is what is the MA's strategy on handling obsolete/deprecated classes. I think I know the answer which is there is no strategy. So let me suggest the following:

1. All classes that are deprecated/obsolete should be visually marked at least (by extending from Modelica.Icons.ObsoleteModel) from the next minor version on (E.g., obsoleted in MSL3.1.x --> extends from ObsoleteModel from at least MSL 3.2.x on).
2. All classes that are deprecated/obsolete should be removed two minor versions later (E.g., obsolete model in MSL3.1.x will no longer be present in MSL3.3.x)
3. The information is clearly and openly publicised and also deprecated/obsoleted classes should be clearly listed in the release notes of MSL together with the clear information when they will be removed. Best in its own section for each release version. Library developers will thus be able to update their own libraries in due time.
4. When removed a conversion script (even though we still only have the unofficial Dymola variant script language available) should take care of renames where possible.

Following those steps no-one should really be able to complain about the MSL breaking their library. If it does then clearly the library developer have not tested their library with the MSL (at all I would say) and we as MA can not take care of the QA of other libraries. As it is the MA is struggling with its own QA enough as it is.

_{PS: *Could any native English speaker (I'd accept AE aswell ;-) ) explain the correct usage of obsolete vs. deprecate. I'm really struggling here to use the right one and so does the MSL as it seems. Thanks!*}

---

Modified by dietmarw on 3 Oct 2014 07:40 UTC
Currently the MSL contains almost 90 classes marked as obsolete/deprecated and with a notice that they will be removed soon.

Now in my 9 years of following the MSL development I can not recall an actual removal having happened even once. So the question is what is the MA's strategy on handling obsolete/deprecated classes. I think I know the answer which is there is no strategy. So let me suggest the following:

1. All classes that are deprecated/obsolete should be visually marked at least (by extending from Modelica.Icons.ObsoleteModel) from the next minor version on (E.g., obsoleted in MSL3.1.x --> extends from ObsoleteModel from at least MSL 3.2.x on).
2. All classes that are deprecated/obsolete should be removed two minor versions later (E.g., obsolete model in MSL3.1.x will no longer be present in MSL3.3.x)
3. The information is clearly and openly publicised and also deprecated/obsoleted classes should be clearly listed in the release notes of MSL together with the clear information when they will be removed. Best in its own section for each release version. Library developers will thus be able to update their own libraries in due time.
4. When removed a conversion script (even though we still only have the inofficial Dymola variant script language available) should take care of renames where possible.

Following those steps no-one should really be able to complain about the MSL breaking their library. If it does then clearly the library developer have not tested their library with the MSL (at all I would say) and we as MA can not take care of the QA of other libraries. As it is the MA is struggling with its own QA enough as it is.

_{PS: *Could any native English speaker (I'd accept AE aswell ;-) ) explain the correct usage of obsolete vs. deprecate. I'm really struggling here to use the right one and so does the MSL as it seems. Thanks!*}

---

Reported by dietmarw on 3 Oct 2014 07:31 UTC
Currently the MSL contains almost 90 classes marked as obsolete/deprecated and with a notice that they will be removed soon.

Now in my 9 years of following the MSL development I can not recall an actual removal having happened even once. So the question is what is the MA's strategy on handling obsolete/deprecated classes. I think I know the answer which is there is no strategy. So let me suggest the following:

1. All classes that are deprecated/obsolete should be visually marked at least (by extending from Modelica.Icons.ObsoleteModel) from the next minor version on (E.g., obsoleted in MSL3.1.x --> extends from ObsoleteModel from at least MSL 3.2.x on).
2. All classes that are deprecated/obsolete should removed two minor versions later (E.g., obsolete model in MSL3.1.x will no longer be present in MSL3.3.x)
3. The information is clearly and openly publicised and also deprecated/obsoleted classes should be clearly listed in the release notes of MSL together with the clear information when they will be removed. Best in its own section for each release version. Library developers will thus be able to update their own libraries in due time.
4. When removed a conversion script (even though we still only have the inofficial Dymola variant script language available) should take care of renames where possible.

Following those steps no-one should really be able to complain about the MSL breaking their library. If it does then clearly the library developer have not tested their library with the MSL (at all I would say) and we as MA can not take care of the QA of other libraries. As it is the MA is struggling with its own QA enough as it is.

_{PS: *Could any native English speaker (I'd accept AE aswell ;-) ) explain the correct usage of obsolete vs. deprecate. I'm really struggling here to use the right one and so does the MSL as it seems. Thanks!*}

---

Migrated-From: https://trac.modelica.org/Modelica/ticket/1578

[modelica-trac-importer]

Modified by dietmarw on 3 Oct 2014 07:40 UTC

[modelica-trac-importer]

Modified by dietmarw on 3 Oct 2014 07:42 UTC

[modelica-trac-importer]

Comment by sjoelund.se on 3 Oct 2014 09:38 UTC
A lot of things have been delayed until the next version with a conversion script, right? And we simply have not had any conversion scripts for the 3.x series at all...
Is this because the conversion scripts have not been standardised or because we wanted a new major version of Modelica?

[modelica-trac-importer]

Comment by dietmarw on 3 Oct 2014 15:08 UTC
This might probably be one reason. But hopefully this can be finally nailed with #1443. Thing is it we need the input of tool vendors for that.

Just one extra remark. I was very conservative when suggesting to wait two minor versions with the removal. Given that we currently have a maintenance version i.e., a x.x.X version every other year (at most) one should probably say that waiting for two minor versions is too long.

[modelica-trac-importer]

Comment by hansolsson on 3 Oct 2014 15:39 UTC
Replying to [comment:4 dietmarw]:

This might probably be one reason. But hopefully this can be finally nailed with #1443. Thing is it we need the input of tool vendors for that.

Just one extra remark. I was very conservative when suggesting to wait two minor versions with the removal. Given that we currently have a maintenance version i.e., a x.x.X version every other year (at most) one should probably say that waiting for two minor versions is too long.

An alternative would be to formulate it in terms of time instead of in terms of versions, i.e. for a new minor or major version (not in a maintenance version such as 3.3.2) we may remove classes that have been obsolete for 'x months'.
Or a combination.

I don't think we want a class marked obsolete in 3.3.2 and then removed two months later in 3.4.0.

However, we need user input for this, and when actually removing them it would be helpful to know how long each currently obsolete class has been obsolete - perhaps the obsolete-annotation could be extended to state that - or just clearly stated in revision-part.

A slight issue with time-based is that we need to formulate it in a suitable way:
User view: Classes that have been obsolete 'x months' may be removed in a new minor or major version.
Internal view: At feature freeze remove classes that have been obsolete 'x months' (either at that time or at the planned release date) - unless there is a very good reason not to. If release dates slip we should not start removing more classes.

[modelica-trac-importer]

Comment by dietmarw on 19 Dec 2014 07:01 UTC
Ticket retargeted after milestone closed

[beutlich]

This has been discussed and decided, see 2018-12-05-Minutes-MAP-Lib-Next-Major-MSL.txt (MA access only).

[cweickhmann]

Technically, this issue still persists:

With my installation of OpenModelica 1.22.1 on a Ubuntu 22.04.3 LTS, even the HelloWorld example shipped with the help files

class HelloWorld
  Real x(start = 1,fixed=true);
  parameter Real a = 1;
equation
  der(x) = - a * x;
end HelloWorld;

simulate( HelloWorld, startTime=0, stopTime=4 )

produces three deprecation warnings which are pretty off-putting for newbies like me, tbh:

record SimulationResult
    resultFile = "HelloWorld_res.mat",
    messages = "LOG_SUCCESS       | info    | The initialization finished successfully without homotopy method.
LOG_SUCCESS       | info    | The simulation finished successfully.
"
end SimulationResult;
OMC-WARNING: 
"[[2:3-2:31](http://fake.url/2:3-2:31)] Warning: Components are deprecated in class.
[<interactive>:[3:3-3:23](http://fake.url/3:3-3:23):writable] Warning: Components are deprecated in class.
[<interactive>:[5:3-5:19](http://fake.url/5:3-5:19):writable] Warning: Equation sections are deprecated in class.
"

[dietmarw]

@cweickhmann There is no such file in the Modelica Standard Library repository. So I guess this is something that the OpenModelica project ships, so you might want to report it there.

[cweickhmann]

I will, thanks for the heads-up. But it's still related to the deprecation issue, imho.

[dietmarw]

Well, there is nothing that can be done here. MSL was corrected wrt that. So if vendors decide to ship deprecated models or documentation that is up to them.

[beutlich]

Should work if you make the (unspecialized) class class a specialized class model:

model HelloWorld
  Real x(start = 1,fixed=true);
  parameter Real a = 1;
equation
  der(x) = - a * x;
end HelloWorld;

[cweickhmann]

Yes, you are right @dietmarw. The issue is with the docs. I'll check where to report that.