A Proposal for

			  Flagging Source File Changes

				      - - -

				  [Proposal #4]

			  Original Draft 19Sep88 - smh

				      - - -


The Problem.

     Whenever one of the several Falcon implementors makes a change to any
source code, there is always a chance that the change wil be incorrect, or at
least will impact some other part of the system in an unanticipated way.  It is
important to be readily able to identify recent changes (and even not-so-recent
changes), because as the ancient programming adage says: "The bug is usually the
last thing you fixed."

     If we were only a single person, it might be possible to rely upon memory
to identify changes.  However, we are many people, and therefore need a
mechanism to make changes visible.  M-X Source Compare is one such mechanism,
but unfortunately, it requires an act of commission, and is clumsy if there are
many scattered changes in a file.


The Proposal.

     Whenever anyone makes a source change to a Falcon source file, he should
flag the change with a comment containing (at least) the following string:

          ||| <userid> <dd><mon><yy>

The three vertical bars are intended to make these comments easily findable
someday when we might want to delete them.  It is of course helpful to include
some brief comment about what was changed.  To make the format clearer, here is
a sample:

          ;; made pkg optional - ||| smh 19sep88
          (defvar lisp-symbols '(
             ...
             array::length			;added ||| smh 19sep88
             ... )

     Although it has been discussed that these comments should appear on
separate lines to facilitate automatic purgation, others have held the position
that this additional formatting requirement will cruftify the code more than it
necessary.  Therefore, these ||| markers may where appropriate be put in
comments on the same line as the code affected.

     The intention is that when a few, small, localized changes are made to a
file, they will be flagged individually using this mechanism.  However, when
extensive systemic changes are made it is reasonable to place a single flag near
the top of each file affected.  If nothing else, this will provide a better
handle for efficiently using M-X Source Compare.

     This proposal is intended to apply to *all* Falcon source files, i.e., all
files which are pointed to by the master K-SYS: K; SYSTEM.LISP file.  This even
includes those lambda files which the cross compiler shares with the native
Lambda compiler.  We might or might not extend it someday to Mac support files,
but they are not presently at issue.