[Axiom-developer] next release

[daly]

> Well, patches are supposed to be posted when they are ready for
> "prime time" use. For "personal" experimentation we don't require
> that (should we?)

Well, clearly "personal" experimentation is a non-issue.

I'm not claiming that anyone has an obligation to share their
local changes. Indeed, the license does not require this either.
However, working together on a common project tends to imply sharing.
But real sharing involves work to "get it off your desk" and into
the common distribution.

The published mechanism for making changes to Gold is to post
  diff -Naur goldcode yourcode >patch
files to the mailing list




I see changes in various files that can be picked up at this time and
would benefit everyone. However, there are several, shall we say,
"challenges":



Challenge 1: SIMPLE CHANGES, such as removing the C prototype
  code is clear, tedious, harmless, and requires no explanation.
  I've already picked up these changes and made sure they happen
  in every file.




Challenge 2: LESS OBVIOUS CHANGES, such as eliding "member" from
  the boot code. This change was made with no documentation added
  to the source code making it impossible to (a) guess why and
  (b) test. Furthermore, there are no test cases so even if I
  understood it I'd have to develop the test cases again (assuming
  you had them in the first place) from scratch.




Challenge 3: ALGEBRA CHANGES. these are clearly beneficial as
  they address known bugs. Unfortunately I'm not an expert in ALL
  of the algebra and I'm adverse to changing what I don't understand.
  (Consider me the first in a long line of people maintaining this 
   code over the next 30 years. If I can't understand it how will they?)
  There was a change to the series code which went into Gold. Now we
  find out that the "fix" was wrong and a new "fix" is proposed. 
  I spoke with Clifton Williamson, the original author of the code, to
  try to validate the original code vs the new fix, so far with no
  decision. Do we want algebra bug fixes to lay around unmerged?
  Do we want to change algebra we don't understand? If we understand
  it do we want to share that information with future maintainers?

  If algebra bug fixes are to be merged we'd need to have some
  explanation of the algorithm so the code could be understood by
  people other than the person who proposed the fix. You need to
  understand the algorithm to fix it anyway so write down what you
  understand so others can understand.

  If algebra bug fixes are to be merged we'd need to have some
  test cases of the algorithm so the code can be checked, especially
  for boundary cases. If you've understood the algorithm and can fix
  it I'd suppose that you had test cases. Publish these as part of
  the fix.




Challenge 4: DEEP STRUCTURAL CHANGES. these are harder to merge as
  they will completely restructure axiom. this will have an impact
  not only on the main line of code but also on every other "private"
  branch of axiom, so it is vital that they are complete, consistent,
  and correct. 

  In order to merge this code it would need a cleanly documented
  pile of code. One of the main project goals is to make sure that
  the system can be maintained. That implies that other people can
  gain an understanding of the code without having to reverse
  engineer it. We're stuck with the reverse engineering task because
  Daly, et.al. didn't document anything. Lets learn from history.

  It would also have to be a diff of Gold since it would be impossible
  to know all of the little dependent pieces that are tucked away
  (e.g. the new axiom-c-macro.h file) or the new handling of
  gcl-cmpinclude.h, etc. You've spent months making GNU configure
  work. Wouldn't it be frustrating to find it badly broken because
  of merging problems?

  Other deep changes, such as a new parser, are also likely to be a
  "challenge 4" task.





> The axiom-commit mailing list has the history of all commits
> to SVN -- when they are not truncated due to SF policy

The axiom-commit mailing list posts are essentially worthless as a
Gold-merge resource. I can reclaim the same information in more detail
by doing 
   diff -r --brief build-improvements gold

What's missing is the (a) changesets (b) documentation (c) tests

The "changeset" mentality is that all of the changes necessary to
produce a final single effect are packaged in a single set of patches.

Changesets are essential to contain all of a change and only a change.
In the current bi/wh branches even simple changes, such as eliding
the C protoype code are spread over multiple commits and not fully
implemented everywhere. The new asq requires new database formats
and changes to the database generation code, all of which have to
happen at the same time.

Documentation is essential because while the axiom-commit says something
cryptic like "fixed bug #NNN", that message is hardly considered a high
quality, "production" piece of code. If we're going to make progress
against the winds of time we've got to consider the future maintainers.

Tests are necessary so that (a) other people can see what the impact
of a change is, (b) we can see what breaks in other peoples' branches
or the gold branch, (c) we can (eventually) regression test and (d) we
can eventually build up a more organized, comprehensive test suite 
like CATS (Computer Algebra Test Suite) that other people can build upon.




Since I'm in the midst of reverse-engineering the build-improvements
and wh-sandbox branches it would be a good time to consider packaging
up changesets for functionality you consider complete and ready. I know
it takes you away from "interesting" axiom tasks. The whole build process
has already cost me several weeks so I understand.

Tim