search

modelica / ModelicaStandardLibrary

Free (standard conforming) library to model mechanical (1D/3D), electrical (analog, digital, machines), magnetic, thermal, fluid, control systems and hierarchical state machines. Also numerical functions and functions for strings, files and streams are included.
https://doc.modelica.org
BSD 3-Clause "New" or "Revised" License
481 stars 169 forks source link

Cleaning up multiple Release notes #2333

Open HansOlsson opened 7 years ago

HansOlsson commented 7 years ago

Looking at #2331 I realized a general issue: several sub-libraries of MSL have "Release Notes" and there does not seem to be a common strategy for them leading the differences and outdated contents.

Most of the sub-library release notes only include changes up to inclusion in MSL, e.g. for Modelica.StateGraph, Modelica.Fluid, Modelica.Media - but some contain some up-to-date changes like Modelica.Thermal.FluidHeatFlow.

From a user-perspective I find that a release note in a sub-library only containing very old changes more confusing than helping: why is this relevant? why are there no changes after 2005?

I would propose moving the sub-library release notes to sub-section(s) of Modelica.UsersGuide.ReleaseNotes, since it seems better than the alternatives:

Just removing them doesn't seem right.

Trying to maintain both the general release notes and package-specific ones seems excessive and will likely not be done correctly.

-- Exactly how to add it is not clear - but one possibility would be that e.g. existing Fluid-release notes could be a sub-section under Modelica 3.1, and in Modelica 3.1 the addition of Modelica.Fluid references this.

dietmarw commented 7 years ago

One thing to keep in mind is that if we would finally go to a modular version of the MSL then those release notes become relevant again. So I would perhaps not yet remove them unless we've already have decided to leave MSL to be a monolithic blob.

So maybe postpone changes here until the next non-backward compatible MSL with conversion script where hopefully MSL will have a strategy again.

HansOlsson commented 7 years ago

One thing to keep in mind is that if we would finally go to a modular version of the MSL then those release notes become relevant again. So I would perhaps not yet remove them unless we've already have decided to leave MSL to be a monolithic blob.

I agree that removing would be bad, and my proposal was to move them to the common release notes - as complete documentation classes - which should make it easy to move it again later.

If we decide to split MSL including release notes we need to consider all information in the current release notes - not just the information before some packages were merged into MSL - especially considering that we might split MSL into smaller of larger parts compared to what was merged into MSL.