[Axiom-developer] Re: Ping: case insensitive filesystems

[Gabriel Dos Reis]

Waldek Hebisch <address@hidden> writes:

| > Not because you can come up with a silly explanation means that any
| > explanation should be silly.  Please, let's keep things in perspective.
| > 
| > What about:
| > 
| >    There are two files for each (special) character glyph, one
| >    for the upper case form, and one for the lower case form.
| >    Historically, the names for these files used to differ only in the 
| >    first character (which is upper case for the upper case form).
| >    That was non-portable and caused griefs on brain damaged file
| >    systems that identify themselves as ``case preserving, case insensitive''
| >    where alpha.ps and Alpha.ps ended up designating the same file.
| >    Consequently, the files for the upper case form have been renamed
| >    to xxx-cap.ps, where "xxx" used to be the historic name.
| > 
| > ?
| > 
| > Please feel free to elaborate/improve it.
| >
| 
| Gaby, we are miscomunicating here.  I wrote about 2006-11/msg00294
| for which _really_ I that best explantion is "remove reference to
| redundant file" (and ChangeLog is _the_ place to put it).
| 
| Expanation you wrote is about 2006-11/msg00297 (you wrote that it
| contains explanation, but in fact explanantion is in the text
| outside the patch). Again ChangeLog is logical place to put
| it.  If you insist on some info outside ChangeLog i would 
| propose to create a new pamplets called "Coding guide" (or
| maybe into DeveloperNotes).


The comment I wrote is effectively for justifying the renaming patch,
which is I thought you're objecting to on the ground that we can find
an explanation that does not look good.  Is that wrong?


For 2006-11/msg00294 I still believe that we need explanation saying
why we removed the redundant file.  This explanation is better placed
in the Makefile pamphlet than the ChangeLog.  Say something like 

  The Axiom system from which this branch had been made appears 
  to contain a redundant copy of util.ht. The version in x/y/z has
  been removed so as to minimize blah.

That needs to go in the Makefile, not the ChangeLog.  When we come to
merge, they will be very helpful -- my experience with GCC branches
makes me very skeptikal of changes on branches that are only (briefly)
described in ChangeLogs.  The patch is approved with that caveat.

When the merge is done, some of the comments will become obselete, but
not before.  When it comes to merge and someone question removal, it
would be much better to point them at the documentation why it
happened.  We would not want to start yet another discussion on
literate programming when we will be busy trying to merge and have a
wonderful system.

| > I'm of the opinion that you get should in the habit of including
| > explanation in the pamphlets when you submit them for consideration.
| > I would like to see the changes explained.  One reason, in this
| > particular case, is that when it comes to merge build-improvements
| > back to trunk (whatever it is called) there will be differences and
| > conflicts, and I would hate to have to spend hours in front of a
| > browser digging in the archive.  Yes, we have ChangeLog files, but
| > they are no substitute for documentation files (which are the pamphlets).
| > 
| 
| Well:
| 1) AFAIU the whole SCM discussion started because we wanted chageset
|    support.

Yes.

|    ChangeLog entry is part of a chageset and would be the
|    first place I would look at during merge.

yes, but a ChangeLog is not a substitute for documentation.  It helps
track changes; it does not explain why changes have been made.  My
whole point is that, yes, we record a change with brief description
(ChangeLog), but we need to explain *why* we made the change.  That
will prove helpful to ourselves when we will face skepticals.

| 2) I you are concerned that ChangeLog is not a pamphlet we can easily

I don't think ChangeLog should be a pamphlet.  Its purpose is to
contain brief description of changes, to assist in archeology.

|    correct this: write a few Latex macros, header and footer. Then
|    a little script can easily convert format (bidirectionally if
|    for some reason we also want conventional ChangeLog).

:-)

| I think we have conflicting paradigms here.

I'm not so sure.

|  I belive that history
| has place in documentation only if it explains _significant_ aspect
| of current system.

The trouble is how to define "significant".  Some people think that if
something changes Axiom to do better error message, it is
significant.  And I agree.  Others think that if it changes any code
in a software that is alredy undocumented, then it is significant
too.  I tend to agree.

|  In case of current filename change past status
| really tells you nothing about new system.

Except that this is a *branch* we are going to merge back to trunk.  We
need to know why we did a change.

-- Gaby