Defining API for minor versions and bug-fixes

[HansOlsson]

I believe we missed this discussion in Lucern, so just adding my existing notes so that they are not lost.

Modelica.UsersGuide.ReleaseNotes.VersionManagement contains the following:

As a recommendation, a valid bug-fix to the maintenance branch may contain one or more of the following changes.

• Correcting an equation.
• Correcting attributes quantity/unit/defaultUnit in a declaration.
• Improving/fixing the documentation.
• Introducing a new name in the public section of a class (model, package, ...) or in any section of a partial class is not allowed. Since otherwise, a user might use this new name and when storing its model and loading it with an older bug-fix version, an error would occur.
• Introducing a new name in the protected section of a non-partial class should only be done if absolutely necessary to fix a bug. The problem is that this might be non-backward compatible, because a user might already extend from this class and already using the same name.

I would propose something like:

• Add something about performance above
• Correct defaultUnit to displayUnit above
• Describe minor version, in addition to bug-fixes it may:
  • Add new classes (in partial packages this may break backwards compatibility, so those changes should only be done if necessary)
  • Modify Examples (including renaming)
  • Add new names in the public section of a class (or in any section of a partial class), even if it may break backwards compatibility but should satisfy:
    • Any new input connector, or connector with annotation mustBeConnected must be conditional and as default not enabled
    • Any new parameter must have a default so that existing uses continue to work
    • Any new function input must be after existing inputs and have a default
    • Any new function output must be after existing outputs
  • Delete/rename names in the protected section of a non-partial class if unlikely to be used
  • Change visibility from public to protected if unlikely to be used

Note that many of these changes may break backwards compatibility in very rare cases. Before you complain that we shouldn't delete protected variables, or change from public to protected note that it was done for MSL 4.1.0 in a few cases, breaking models like:

 model A 
   extends Modelica.Mechanics.MultiBody.World;
   parameter Integer x=ndim_pointGravity;
   annotation(uses(Modelica(version="4.0.0")));
end A;

Basically, there's a trade-off:

• One could bump major version for any change - regardless of how unlikely it is that it breaks things; the likely consequence is either that good changes are delayed way too long, or that every new release is a major version
• One could just have no rules, and things will break all the time.

Restricting it to "minor version" and only changes that seem unlikely to cause problems seems like a good compromise.

[HansOlsson]

Also add the user perspective:

You can rely on MSL to be backwards compatible for bug fixes versions and practically backwards compatible for minor versions.

Provided you don't rely on any of the following:

• Models that are marked as Example or documentation models in MSL. You can use them for inspiration and copy the Examples, but directly using Example models in user models should be avoided.
• Combing extending a non-partial class from MSL with named elements (either directly or indirectly by using multiple inheritance).
• Clear bugs in MSL (as an example, if the model should have multiplied a parameter by 10 in some case, don't use the component for that case while compensating for the bug by setting the parameter to a tenth of the actual value).

Incompatible changes for major versions are generally handled using conversion scripts provided with the new version.

Note:

• The text is preliminary, I could change to a pull-request..
• I'm also fully aware that "Clear bugs" item is stupid, but it is an actual possibility.
• I haven't listed the user-perspective for "variables that are unlikely to be used".