Proposal for TEI file-locking procedures TEI ED A40, CMSMcQ, 8 June 1993, rev 2 Aug 1993 Revision of TEI P2 and P3 will involve changes to many files; this document proposes a method of keeping the files in synch and avoiding simultaneous update by different editors. 1. For each file, there exists one and only one 'master' copy, which resides on a specific machine in a specific directory. To wit: - chapter files reside on gluon.cc.uic.edu in home/TEI/gluon - tagdoc, entdoc, and classdoc files reside on onions.natcorp.ox.ac.uk in home/TEI/onions 2. Each machine should be set up to be able to mount appropriate subdirectories of the other machine using NSF. (This now works from gluon, but not from onions. We will keep trying.) 3. For cases of network outage, and for performance reasons, r/o versions of all files may be kept on both gluon and onions, in /home/TEI/fallback; these should be used when validating files, etc. 4. The /home/TEI/fallback directories should be automatically refreshed from time to time. (Tentatively, twice a week on Monday night/Tuesday morning and Thursday night/Friday morning, about 9 p.m. CDT, 3 a.m. GMT.) This can be done with a shell script. (Not implemented yet.) 5. The 'master' copies of all files should be kept in a revision control system, to minimize problems of concurrent updating. We use RCS for this purpose. The RCS copies of all files are in the appropriate RCS subdirectories: - chapters in gluon.cc.uic.edu:home/TEI/gluon/RCS - reference crystals in onions.natcorp.ox.ac.uk:home/TEI/onions/RCS 6. The copies in /home/TEI/gluon and /home/TEI/onions should be read-only. Read-write copies should be checked out from private directories: - chapters in ~/TEI/p2 - reference crystals in ~/TEI/p2/tags Each of these directories should have a symbolic link to the appropriate RCS directory: cd ~/TEI/p2 ln -s /home/TEI/gluon/RCS RCS cd tags ln -s /home/TEI/onions/RCS RCS 7. The normal procedure for changing a file is this (for example, to change blort.tag): a. log on to onions (or gluon, for a chapter) b. go to the r/w directory: cd ~/TEI/p2/tags c. check the file(s) out for revision. co -l blort.tag If the file is already locked, then do one of the following: - wait until it's unlocked - pester the other editor until it's unlocked - Check the file out for revision on a side branch, and plan to reconcile the duplicate versions later: co blort.tag When checking this back in, see special instruction for side branches. - break the lock and check the file out: rcs -u blort.tag co -l blort.tag The first command will result in a note being sent to the current holder of the lock explaining that you have broken the lock. d. Edit the files on this or any machine. After editing, move them back into ~/TEI/p2/tags if necessary. e. Check in the revisions: i. Note the revision number currently in the file (e.g. 1.2) ii. Check the file in: ci blort.tag iii. Note the revision number RCS now gives the file (it will appear in the RCS message). It should be one revision higher than the one you checked out; otherwise you have skipped a revision and overwritten later changes. (E.g. if you checked out version 1.2, the version you check back in should get the number 1.3: if instead it gets 1.4, you must reconcile your changes in 1.4 and those made in 1.3.) It is the responsibility of the person checking in a file to see that no changes are dropped due to simultaneous update. For side-branch checkin and other special cases, see next item in this list. f. Make new read-only copies to be picked up when needed: cd /home/TEI/onions co blort.tag 8. Special circumstances and side-branch checkins: Under some conditions, the normal procedure won't work. If it is not possible to check the file out properly or to delay editing it, then a read-only copy may be edited (but should not be placed back in the read-only directory!) and later checked in as a revision. This is fine if and only if the version you worked from (the read-only version you edited) is still the current version. If it's not still the current version, then the file has been changed already by the other editor (after all, you didn't have it locked) and the two sets of revisions must be merged. In general, the procedure is this: a. edit the read-only version of the file you have available to you. b. lock the file retroactively (if it's currently locked by the other editor, wait, or negotiate, or work on a branch) rcs -l blort.tag c. verify that the current version is the same as the read-only version you worked from (check the revision number): rlog blort.tag d. if it has been changed, then ... you must merge the two sets of changes. Check the file in on a branch and use rcsdiff to locate the differences. Then merge the two versions using whatever tools your wits devise (look up rcsmerge, too). E.g. if you worked from 1.2, but the file is now locked or has already been updated to 1.3: ci -r1.2.1 blort.tag rcsdiff -r1.2.1 -r1.3 blort.tag d bis. if the current version has not changed since your read-only version was generated, then ... check in your revisions normally. ci blort.tag Avoiding Simultaneous Update It seems clear that in the circumstances we imagine, it would be very handy for the revision control system to recognize, from a file being checked in, what version it was created from, and to refuse to accept it if that version is no longer the current version of the branch in question. With this facility, the following sequence of events would be legal and unproblematic: user lou issues command 'co blort.tag', receiving version 1.1 user msmcq also gets a read-only copy of version 1.1 user lou edits the file user lou issues command 'rcs -l blort.tag' to lock it retroactively user lou issues command 'ci blort.tag' to create version 1.2 This is unproblematic as long as msmcq gets version 1.2 reasonably soon -- before he edits it himself. The following sequence of events, on the other hand, needs to result in an error message: users lou and msmcq each issue command 'co blort.tag', receiving version 1.2 user lou edits the file user lou issues command 'rcs -l blort.tag' to lock it retroactively user lou issues command 'ci blort.tag' to create version 1.3 user msmcq edits the file too (starting from 1.2) user msmcq issues command 'rcs -l blort.tag' to lock it retroactively user msmcq issues command 'ci blort.tag' to update it, creating version 1.4 and losing lou's changes from 1.2 to 1.3 In the system we need, the system should notice either when the file was locked retroactively, or when the second update was performed, that msmcq's copy of blort.tag was an edited variant of version 1.2, and not of the current version 1.3; it should refuse to lock the file, or refuse to check in the changes creating version 1.4, unless a 'force' or 'yes i really mean it' flag was given on the command. Unfortunately, RCS does not notice this problem automatically: we must take care to check for it manually, as described above.