Improve DICTIONARY_AUDIT summaries before release. #361
Conversation
As the git repository stores the details of all changes, only the most significant changes need to be recorded in the dictionary audit area. The significant changes are generally new categories and data names, or deprecation of old data names. Corrections or changes to types and units have generally been covered by generic statements.
The original said the change was to version 4.0.1. The current conformance is version 4.1.0. Rather than note every change of DDL version, the step to version 4 is the most significant.
|
Could the full changelog be retained somewhere (e.g. as a separate file)? It is really useful when developing the software to be in-line with the changes. |
|
In what ways is the git changelog insufficient? E.g. v3.0.13...master? If those are not good enough, it seems to me that it would be possible going forward to improve the standard of our commit comments to make the automatic git changelog better than the one in the cif_core.dic file. The way I imagine things working is that you'd look through the cif_core.dic record to see where a data name or category was added, and then if you're interested in the reasons you'd use git to find the relevant commit. There's also git blame and so on. |
|
The git logs have several drawbacks from my point of view. Firstly, they are localised to the git repo and are therefore not distributed alongside the dictionary (e.g. in Zenodo). Furthermore, there is also a risk of squashing the relevant commits or losing the commit history while migrating to another repository (probably unlikely, but still a possibility). Finally, the long form CHANGELOG is already curated, i.e. the commit authors have highlighted the most important changes, while the git changelog may contain intermediate commits which may even revert previous changes made in the same development period. I am mainly suggesting this for convenience and readability. Of course, if no one else sees any benefit in this, I can always keep the more detailed list off-site for my own purposes. :) |
As the released dictionaries contain only a summary of the most important changes, a detailed changelog has been added to preserve the more detailed change lists that build up during the development of a new version.
|
I have added a separate file containing the unsummarised list of changes. Please adjust as you see fit and then we can merge and create a release candidate. |
|
Also, the git commit list will contain many spurious changes associated with fixing errors from previous commits, and other things which don't add value. |
The release summaries in the dictionary_audit categories have been shortened to highlight only the most important changes. Once this PR is accepted, we will create a release branch and the current dictionary will become the release candidate.