>while a descriptive history is good, it takes a lot of extra work >to generate.
i've rarely found per-change histories to be any more useful than most other comments, i'm afraid. you'd hope it would answer "what was he thinking?" but i found either it was obvious or i still had to ask. still, perhaps it could be regarded as an aid to future computer archaeologists, after all shared context has been lost. the intention of things like /CHANGES is mainly to point out moderate to large changes (eg, if you've been waiting for a bug fix or there's a significant change to usage or operation). it isn't intended to give details or rationale of the fix, any more than there is any of that for the original code, really. perhaps literate programming will fix that if it ever takes off. (the set of people that write good descriptions and the set of people that write good code don't necessarily have a big intersection.) for larger additions or changes i sometimes wrote short notes giving the background, the changes/additions and the rationale for them, ranging from the equivalent of a long e-mail to a several-page paper. that worked quite well, but was somewhat more work. also useful for compilers are links to bug demonstration programs and regression tests. the advantage of dump and snap is that the scope is the whole system: including emails, discussion documents, the code, supporting tools -- everything in digital form. if software works differently today compared to yesterday, then
