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
472 stars 169 forks source link

Edit Modelica.UsersGuide.ReleaseNotes.Version_4_1_0 #4260

Open beutlich opened 8 months ago

beutlich commented 8 months ago

Just to not forget about it:

The tables in Modelica.UsersGuide.ReleaseNotes.Version_4_1_0 for

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

4251 can be considered as a start here.

Harisankar-Allimangalath commented 8 months ago

@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

  1. The Table format , which is the present MSL release note format ,
beutlich commented 8 months ago
  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).

  1. 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

beutlich commented 8 months ago

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).

  1. 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

  2. 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 commented 8 months ago

@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 commented 7 months ago

@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 commented 7 months ago

@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 commented 7 months ago

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

tobolar commented 7 months ago

@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 commented 7 months ago

@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 commented 7 months ago

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