[Axiom-developer] Re: Revision history

[William Sit]

Ralf Hemmecke wrote:
> 
> > As Bill, I think hard-coded modification date is preferable, as it
> > allows minor modification (e.g. fixing typo). Of course, it depends on
> > the semantics you espect on the date.
> 
> I also vote for hardcoded version or date information in a file. If you
> take the modification time of the file, it might be a bit confusing if
> an identical file appears in another branch of Axiom. Those two files
> will probably have different times and all you see in the .dvi is that
> they seem to be different.

Why would two identical files have different modification time? I
suppose people are not careful with using -p to copy files? Ok, forget
that, but then insist that \date appears hardcoded.
 
> > William Sit <address@hidden> writes:
> >
> >> Come to think of it, each pamphlet file should include a revision
> >> history, with dates, much like code. So we should have latex macros
> >> \creationdate, \revisiondates, and \filedate (which may be included in
> >> \revisiondates).
> >
> > Doesn't that revision history belong to the changesets of the Source
> > Code Management system, whichever it is?
> 
> I am also wondering why we would use some SCM and then hardcode
> \creationdate, etc. You can use, for example, "svn log FILENAME" and get
> all the wonderful history.

There is a difference: when such info is given in the pamphlet file, it
is given in context, not as logs. Moreover, one has to actively ask for
the log, but if there is no indication in the pamphlet file, where would
one get a reason to look through a log file? Imagine that in my recent
revision of Tim's autodoc.lisp.pamphlet, if I had checked out the
original, made the revisions, checked it back in and documented the
revision notes separately at check-in, then when someone reads my
version, it would just look like an original document, where there would
be no indication why I made the changes (that info would be kept as a
terse comment when I checked the revision in) and a trip to the
changeset or diff file wouldn't work because the revision is a total
rewrite. I don't know how Tim applies patches, but if it only involves
removing the minus lines and insert the plus lines, someone reading the
source code would not be helped unless the changes are documented in the
pamphlet file -- but that would meant maintaining revision history
(albeit not necessarily with dates) in the pamphlet file itself.

Since I am not a developer (certainly not the system-related stuffs), if
SCM already maintains history info to your satisfaction, good for you.
My own experience is that I seldom would have the need to retract back
to a certain date since I don't remember what particular date would
still have a working version. Rather, if some half-baked ideas in an
attempted new version did not work out, I would revert completely to a
previously frozen version that I know worked and start over. Even that
is quite seldom, and often I just keep working until the half-baked
ideas got cooked and working, then I freeze and save it and proceed to
explore other ideas.

William