Revisions

It is very important to add a <change> in the <revisionDesc> element of the <teiHeader> at the end of each section of work of improvement of a record. In the attribute @who enter your id, in the @when enter the date of the change, in the format YYYY-MM-DD. You can use code templates in oXygen to do this. There is a set ready for you which also includes this. Inside the element, briefly describe the changes you have made.

<revisionDesc> <change when="2010-12-04">registered</change> <change who="DN" when="2015-09-11">last edited</change> <change who="PL" when="2016-03-10">transformed from mycore to TEI P5</change> </revisionDesc>

Best thing would be to do this every time you are not simply adding a comma.

The file should be submitted for revision to a second author taking care of describing according to guidelines the event.

  1. Cataloguer will enter a <change> with content Submitted for review, once she is finished.

  2. Reviewer will add a <change> with content Reviewed and Corrected,

  3. General editor will enter a <change> with value Approved

If you change for example an ID in many files you don't want to go back to each and add a <change>, but in that case there is also the GIT commit message which will help. Please use it! There is no need to commit immediately every small change made, thus multiplying them and their titles and descriptions, but when we do commit something (after checking, validating, checking again and being very sure), it is extremely important to give a proper title and any relevant information helping to investigate the change in the future.

If one has to revert a commit of 40 files and all the commit says is "update" and there is no change element, anyone looking into the commit which caused the issue is forced to do hand comparing on each commit to find out which one might contain the mistake and then check each file by hand, i.e. the whole workflow and file versioning is rather vain.

The <revisionDesc> in the files and the commits to GIT (titles and descriptions) are our way to keep track of the work easily and they become more and more important as we proceed, so please let us not skip these steps, they are not time consuming and they are of great importance in the short and long term.

In <change>, please describe what you have changed in the file, e.g. "added msItems and transcription of divs".

In the commit title, try to provide a descriptive title which will make it as easy as possible to know at a glance what you have committed there. so, "added IDs" is way much better of "minor correction" (and shorter!) "added perName elements" is better than "changed something".

You can use the commit description to link and refer to issues, if the explanation of what you have done is there. The issue will also receive that information and provide a link to the commit.

This page is referred to in the following pages

Revisions of this page

  • Pietro Maria Liuzzo on 2018-04-30: first version of guidelines from Wiki