Revision of RevisionHistory

[christiankral]

The guidelines on writing revisions of Modelica classes are summarized in Modelica.UsersGuide.Conventions.UsersGuide.RevisionHistory. In this documentation class an example summarizes the actual recommendations:

Actual guidelines

The actual guidelines have some drawbacks which do not match the actual development process:

1. Version
   • When a change is performed, one may not exactly know what the next version number exactly will be (e.g. 4.1.0 or 5.0.0)
   • Additionally, a bug fix will most like be back ported to e.g. 3.2.3+maint and 4.0.1; so putting only 3.2.3+main to the revision notes may be misleading as 4.0.0 was also released with a bug which was fixed afterwards
2. Date
   • Some years ago one just committed a change to the subversion server and this allowed it to put an exact date into the revision history (consisting of year, month and day)
   • Today we use pull requests (PR) which may go over several weeks and months; so there is not one exact date I can state in advance when I create the PR.
3. Author
   • Today we may not have just one author performing the changes, but a group of people discussing issues who thus directly and indirectly contribute to handling an issue
4. Comment
   • Revision comments are very important for severe bug fixes as in Complex.scalarProduct not a scalar product #1260 and Complex transfer function block uses wrong order of coefficients #3651
   • Most importantly, the guidelines on revision history are mostly not applied at all; the majority of Modelica classes does not show any entry in the revision history
   • I am reluctant to manually add a lot of information to the Modelica documentation which is already available on GitHub; I yet think that (severe) bug fixes have to be explicitly stated in the revisions, as a user cannot always go through the entire GitHub history to understand what bugs have been fixed

Proposal

1. Provide a general link to the history of changes on GitHub
   • For Modelica packages which are already split into individual files, it is very simple to provide such a link
   • I wonder if for non-split Modelica packages there is a way to provide such history information, as it was partly discussed in Proposal to split MSL into single files #2975; possibly some static meta information is required to perform this "job"
   • I wonder if such an automatic link of the revision history could be provided by the Modelica tools
2. Provide much simpler manually added revision history into a bullet point list:
   • Year (when the issue was reported or the process of working on it was started)
   • Author optionally, when migrating from the old to the new format
   • Comment on a bug fix (and other (?) important) note
   • Step by step remove "obscure" version numbers which way back in time have not been in line with the MSL versions numbers, e.g. in the revision history of Modelica.UsersGuide.Conventions.UsersGuide.RevisionHistory

Example Modelica.Electrical.Analog.Basic.Resistor

Actual revision history

Proposal of new revision history

The GitHub link shows:

This example may not be the "best" example in terms of revision history, it is an example of combining existing revision history information with a GitHub link.

Example Modelica.Magnetic.QuasiStatic.FundamentalWave.BasicMachines.SynchronousMachines.SM_PermanentMagnet

[beutlich]

I'd prefer not to link to the file history of GitHub. That does no sound useful to me. For me the revision history should document relevant changes from the user's perspective. It might be useful to also link to the GitHub issue or pull request, but not as general rule.

[dietmarw]

I'm all for a simplified revision history as suggested. Like @beutlich I think providing the file history link might get confusing and rather providing relevant issue or pull-request numbers if necessary might be better.
In addition I like to propose to stick with the ISO 8601 date format (YYYY-MM-DD) as in the current recommendation, since it is easier to sort and visualise.

[tobolar]

In addition I like to propose to stick with the ISO 8601 date format (YYYY-MM-DD) as in the current recommendation, since it is easier to sort and visualise.

Possible, if its clear how an exact date shall be identified.

[dietmarw]

Luckily, ISO 8601 is very clear and concise in this respect.

[HansOlsson]

ISO 8601

So the dates above would be 2009-08-07, 2009-03-11, 1998.

All valid according to ISO 8601; https://en.wikipedia.org/wiki/ISO_8601

[dietmarw]

Yes exactly.

[tobolar]

Sorry for I didn't express myself correctly. What I mean is the note of @christiankral:

Today we use pull requests (PR) which may go over several weeks and months; so there is not one exact date I can state in advance when I create the PR.

So how is meant this one single date in the history of a revision. When someone report it, or start working on it, or the first PR...?

[dietmarw]

Well does that matter? Is it really an issue if you created a model, filled in the revision history and then created the PR and then it will take some time until the PR gets finally merged. The original idea and implementation was still done at that date and one could still decide to updated it if one feels like it. But in all honesty I don't think it matters.

[christiankral]

OK, so the summary here is so far:

• We rather go for a simplified revision history format
• We do not specify what revision date actually represents
• We use the ISO 8601 date format
• We do not link the Github revision history

[dietmarw]

Sounds good to me.

[christiankral]

OK, then the simplified revision history format (without version numbers) is then:

I fully understand: the more rules we have, the more rules will be broken and violeted. So it make sense to better keep this a recommended format in the Modelica User's Guide. So we could actually add the simplified format to the original revison format based on a table to the User's Guide.

Yet I would always recommend to start the revision text in Uppercase and sperate it from the author by a :