Open christiankral opened 3 years ago
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.
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.
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.
Luckily, ISO 8601 is very clear and concise in this respect.
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
Yes exactly.
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...?
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.
OK, so the summary here is so far:
Sounds good to me.
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 :
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:
Proposal
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