Add implementation notes.

diff --git a/src b/src
index cadb2228c69b92f0f439d55132e66e3abf1eb6eb..8713c83b5c302e0590cd433386fcb20c5dfc17fe 100755 (executable)
--- a/src
+++ b/src
@@ -2,6 +2,25 @@
 #
 # src - simple revision control.
 #
+# Things to know before hacking this:
+#
+# All the code outside the RCS class is intended to be generic to any
+# file-oriented VCS. Try to keep it that way; in particular, support
+# for SCCS is an eventual goal.
+#
+# SRC and RCS have different goals in managing locks. RCS wants to keep
+# the workfile read-only except when it's explicitly checked out, SRC wants to
+# leave it writeable all the time.  Thus, the checkin sequence is "release
+# lock; check in; assert lock". If this seems confusing, it's because in
+# RCS rerminology, locked is writeable and unlocked is read-only.
+#
+# The "src status" command needs to be fast so that Emacs VC won't be sluggish.
+# It's written to only have to access the inodes of each master and workfile,
+# not the files themselves.  The central trick is the use of utimes(2) to
+# set the master's modification time just after the workfile is checked out;
+# thus, to distinguish between U and M status all we need to do is compare
+# modtimes.
+#
 import sys, os, subprocess, time, calendar, stat, glob
 
 version=0.2
@@ -820,7 +839,7 @@ class RCS:
         # log display.  This gives us plenty of slack to cope with
         # minor format differences.
         #
-        # The motivation here is to make "src status" faster by avoid
+        # The motivation here is to make "src status" faster by avoiding
         # the need for an entire log parse when checking for "A"
         # status.
         return os.path.getsize(self.master(arg)) > 105