Open vaitkus opened 5 years ago
Regarding point (3), I think it is unnecessary for each contribution to change dictionary_audit.revision. Assuming #141 is accepted, I would prefer that changes to _dictionary_audit.revision occurred when a new version is released. The Github history will contain all changes, and a nice summary can be created from this when the new version is released. Until that time, we can put placeholder text in the final entry to say "refer to the git history".
I had two main arguments in mind when suggesting point (3) which were mainly inspired by the recommendations of keeping a CHANGELOG of ones software:
CHANGELOG
as the changes happen than to comb through the logs just prior to a release. Factors like people forgetting things, people not be available for additional comments and the sheer scope of log messages to go through make sure of that. Of course, a dictionary is not a piece of software, but I'd image that the same principles would apply.However, I do understand that there might be some specifics of managing an ontology (low commit count, low change rate, etc.) that transform the constant log keeping to more of a busywork than a benefit.
Current practice seems to be developing towards documenting all non-trivial changes in the dictionary_audit log, as @vaitkus suggested.
I have some plans to create a proper procedure in COMCIFS for document creation, with a technical committee for technical procedures such as this one. Meanwhile, if @vaitkus would like to draft a document covering the above in comcifs.github.io/draft, that would be very helpful. I note that github actions such as the one proposed in #228 could help contributors find overlooked problems, such as no dates updated relative to the master branch or dictionary_audit not updated. Of course, even if such checks failed they could be ignored for trivial updates.
This issue is somewhat related to issue #141, however, it tackles the same problems from the point of the contributor. Here are several suggestion that could be included in GitHub contributing guidelines for the repo.
Question 1: how should changes made to the dictionaries be described?
There are several mechanisms in the DDLm that are used to track and register the dictionary change history: 1) The
DICTIONARY_AUDIT
loop registers the new dictionary version number, date of the version release and provides a short human-readable description of the changes that have been applied; 2) The_dictionary.date
data item contains the date of the last change applied to the dictionary. In stable dictionary releases this date should match the date of the latest version release in theDICTIONARY_AUDIT
loop; 3) The_definition.update
data item is provided in each definition and contains the date of the last change applied to this individual entry.When presenting a PR the following changes should be applied by the contributor: 1) Any non-trivial change to a definition must be registered using the
_definition.update
data item by changing its value to the current date; 2) Any non-trivial change to a dictionary must be registered using the_dictionary.date
data item by changing its value to the current date; 3) Any non-trivial change to a dictionary must be registered using theDICTIONARY_AUDIT
data loop. The registration is carried out by modifying the latest loop entry rather than adding a new loop entry. The latest_dictionary.date
data item value should be changed to the current date and a short description of the changes should be appended to the latest value of the_dictionary_audit.revision
data item. The version number must remain unchanged.NOTE: in case proposals from issue #141 get accepted the latest
_dictionary_audit.revision
value would simply contain the CHANGELOG of the developmental dictionary version.