Edit Modelica.UsersGuide.ReleaseNotes.Version_4_1_0

[beutlich]

Just to not forget about it:

The tables in Modelica.UsersGuide.ReleaseNotes.Version_4_1_0 for

• added libararies (if any)
• added components
• updated components (keeping backwards-compatibilty)
• updated components (breaking backwards-compatibilty)
• critical bug-fixes

need to be (manually) edited before a final release of MSL v4.1.0

#4251 can be considered as a start here.

[Harisankar-Allimangalath]

@beutlich @casella just for clarification and understanding .

1. I was working on this release notes generation script mentioned on #4251 , and came across something like Pandoc which can be used for HTML and PDF generation its a free tool . so after downloading the dependencies (Miktex , pdflatex ) and modifying the script I was able to generate the HTML(using the old template available ) PDF (without watermark) . I shall attach the modified script , and generated documents here . wanted to know should I be proceeding with this .

ResolvedGitHubIssues.md ResolvedGitHubIssues.pdf Release_note_generator.txt

2. The Table format , which is the present MSL release note format ,

• do we have a template for that ?
• can we generate it using that template and existing script ?
• how was it done last time ?

[beutlich]

1. I shall attach the modified script , and generated documents here . wanted to know should I be proceeding with this .

Well, as you like. In my opinion it can be easily scheduled after v4.1.0 is released since we have a working solution right now: https://github.com/modelica/ModelicaStandardLibrary/actions/workflows/generateReleaseNotes.yml -> Run workflow (w/ or w/o watermark).

2. The Table format , which is the present MSL release note format ,
   • do we have a template for that ?

There are five tables:

1. The following new libraries have been added:
2. The following new components have been added to existing libraries:
3. The following existing components have been improved in a backward compatible way:
4. The following existing components have been changed in a non-backward compatible way:
5. The following critical errors have been fixed (i.e., errors that can lead to wrong simulation results):

Each table has the same layout, that you can copy if not yet done.

* can we generate it using that template and existing  script ?

Editing release notes usually is manual work. Probably AI can be of help nowadays.

* how was it done last time ?

Editing release notes used to be manual work. The MAP-Lib project leader and library officers need to decide which of the many changes is worth and relevant for the MSL end user (aka simulation engineer). Of course the input of

• the ResolvedGitHubIssues.md (e.g., https://doc.modelica.org/Modelica%204.0.0/Resources/Documentation/Version-4.0.0/ResolvedGitHubIssues.html)
• the commit history and
• the Comparison Summary (created by Dymola) (e.g., https://doc.modelica.org/Modelica%204.0.0/Resources/Documentation/Version-4.0.0/DifferencesTo323.html should be considered.

[beutlich]

Given the MSL library comparison of #4300 I see the following classes (besides the ones already documented) that should appear in the release notes (to the best of my knowledge).

4. The following existing components have been changed in a non-backward compatible way:

Blocks.Continuous.LimPID Blocks.Discrete.Sampler Blocks.Discrete.ZeroOrderHold Blocks.Math.ContinuousMean Blocks.Sources.ContinuousClock Electrical.PowerConverters.DCAC.Control.SVPWM Magnetic.FundamentalWave.BaseClasses.Machine Magnetic.QuasiStatic.FundamentalWave.BaseClasses.Machine

5. The following critical errors have been fixed (i.e., errors that can lead to wrong simulation results):

Complex.'*'.scalarProduct ComplexBlocks.ComplexMath.TransferFunction ComplexBlocks.Sources.ComplexRampPhasor Electrical.Batteries.Utilities.PulseSeries Electrical.Polyphase.Basic.Resistor Electrical.Polyphase.Basic.Conductor Electrical.Polyphase.Basic.VariableResistor Electrical.Polyphase.Basic.VariableConductor Magnetic.FluxTubes.Shapes.FixedShape.HollowCylinderAxialFlux Magnetic.FluxTubes.Shapes.FixedShape.HollowCylinderRadialFlux Magnetic.QuasiStatic.FluxTubes.Shapes.FixedShape.HollowCylinderAxialFlux Magnetic.QuasiStatic.FluxTubes.Shapes.FixedShape.HollowCylinderRadialFlux Mechanics.MultiBody.Frames.Quaternions.from_T Mechanics.MultiBody.Sensors.Internal.BasicAbsoluteAngularVelocity Fluid.Fittings.BaseClasses.QuadraticTurbulent.LossFactorData.sharpEdgedOrifice Fluid.Utilities.regFun3 Media.Air.MoistAir.Utilities.spliceFunction Media.Air.MoistAir.Utilities.spliceFunction_der Media.Air.ReferenceMoistAir.Utilities.pd_pTX_der Media.R134a.R134a_ph.dofpT Math.isPowerOf2

Of course, the library comparison only lists the changed class. If there are classes that use a changed class as component (and thus are also affected by the change) it should be ideally mentioned. The library officers shall advice here.

I did not check for tables 2 and 3.

[Harisankar-Allimangalath]

@beutlich in the previous message what did you mean by "besides the ones already documented" we are only going to document it right , so the new Release note only contains the ones mentioned above plus what we add along , and is there a way I could easily figure out the content for other tables ?

[Harisankar-Allimangalath]

@HansOlsson @beutlich @maltelenz @MartinOtter I have created a branch to work on the release notes ,have been adding things based on the information from above messages and would like to inform all the Library officers to look into it and contribute so do we have a way to do that other than Tagging everyone here .

[Harisankar-Allimangalath]

@AHaumer @MartinOtter @christiankral @HansOlsson @tobolar @casella , I have created a branch to work on the release notes and added things from the above list , the exact change associated with each is added as the corresponding ticket heading and needs to edited at some places , but I would like to get input from other library officers on the content to added for other tables , and the existing one can be seen as a draft to build upon .

[beutlich]

Can you create a draft PR from this branch. Would make life easier for reviewers.

[tobolar]

@AHaumer @MartinOtter @christiankral @HansOlsson @tobolar @casella , I have created a branch to work on the release notes and added things from the above list , the exact change associated with each is added as the corresponding ticket heading and needs to edited at some places , but I would like to get input from other library officers on the content to added for other tables , and the existing one can be seen as a draft to build upon .

I'm not sure how shall I proceed. Shall we contribute to that branch? Or just to comment on it - then please consider https://github.com/modelica/ModelicaStandardLibrary/issues/4260#issuecomment-1945525527 If the contribution is desired, which file shall we modify? md or html?

[Harisankar-Allimangalath]

@tobolar @beutlich #4327 is created for issue. and from my understanding it is desired to edit the release notes.html files (Modelica/Resources/ReleaseNotes/Modelica.UsersGuide.ReleaseNotes.Version_4_1_0.html) directly .The other edited files starting with "Resolvedgithubissues...." are autogenerated and also needs update as new PR is closed but can be easily generated with the script .

[AHaumer]

For the next release we should consider splitting Modelica.mo into single files (to enable easier handling of release notes)