Octave Snapshots -- general info

Last updated: Mon May 23 18:58:05 1994

This file was adapted from a similar document written by Fred Fish and
used by the GDB developers.

Snapshots are an "image" of the main Octave development tree, captured
at a particular random instant in time.  When you use the snapshots,
you should be able to maintain a local copy of Octave that is
reasonably close to the official source tree used by the Octave
maintainers.

The primary purpose of providing snapshots is to widen the group of
motivated developers that would like to help test, debug, and enhance
Octave, by providing you with access to the "latest and greatest"
source.  This has several advantages, and several disadvantages.

    First the advantages:

    o	Once we have a large base of motivated testers using the
	snapshots, this should provide good coverage across all
	currently supported Octave hosts and targets.  If a new bug is
	introduced in Octave due to fixing another bug or ongoing
	development, it should become obvious much more quickly and
	get fixed before the next general net release.  This should
	help to reduce the chances of Octave being released to the
	general public with a major bug that went unnoticed during the
	release cycle testing because they are machine dependent.  We
	hope to greatly improve Octave's stability and reliability by
	involving more people and more execution environments in the
	prerelease testing.

    o	With access to the latest source, any diffs that you send to fix
	bugs or add new features should be much easier for the Octave
	maintainers to merge into the official source base (after
	suitable review of course).  This encourages us to merge your
	changes quicker, while they are still "fresh".

    o	Once your diffs are merged, you can obtain a new copy of Octave
	containing your changes almost immediately.  Thus you do not
	have to maintain local copies of your changes for any longer
	than it takes to get them merged into the official source
	base.  This encourages you to send in changes quicker.

    And the disadvantages:

    o	The snapshot you get will be largely untested and of unknown
	quality.  It may fail to configure or compile.  It may have
	serious bugs.  You should always keep a copy of the last known
	working version before updating to the current snapshot, or at
	least be able to regenerate a working version if the latest
	snapshot is unusable in your environment for some reason.

	If a production version of Octave has a bug and a snapshot has
	the fix, and you care about stability, you should put only the
	fix for that particular problem into your production version.
	Of course, if you are eager to test Octave, you can use the
	snapshot versions in your daily work, but users who have not
	been consulted about whether they feel like testing Octave should
	generally have something which is at least as bug free as the
	last released version.

    o	Providing timely response to your questions, bug reports, and
	submitted patches will require the Octave developers to
	allocate time from an already thin time budget.  Please try to
	help us make this time as productive as possible.  See the
	section below about how to submit changes.


How to get the snapshots
------------------------

The current plan is to provide a full snapshot every week or so.  For
now, diffs from previous versions will not be available.  The files
will be available via anonymous ftp from bevo.che.wisc.edu, in the
directory /private/octave in the form of a tar files compressed with
GNU gzip.  You can ftp gzip from bevo.che.wisc.edu in the directory
/pub/gnu.

Even though the snapshots are available in a public place, we ask that
recipients not widely publicise the availability of the snapshots.
The motivation for this request is not to hoard them, but to avoid the
situation where the general Octave user base naively attempts to use
the snapshots, has trouble with them, complains publicly, and the
reputation of Octave declines because of a perception of instability
or lack of quality control.


Octave test suite
-----------------

A test suite is distributed as an integral part of the snapshots.
However, to use it you will need to get a copy of the dejagnu testing
framework.  Snapshots of dejagnu are available alongside the Octave
snapshots, using the same naming conventions as the Octave snapshots.
Once you have installed the dejagnu framework, a simple "make check"
in the Octave directory should be sufficient to run the tests.

Note that the test suite is still quite limited.  The test framework
itself might not install on your system if you have an environment
that is not similar to one that the Octave developers already use.
The tests themselves only cover a small portion of Octave features,
and what tests do exist for a feature are not exhaustive.  New tests
are welcomed.


Getting help, Octave discussions, etc.
--------------------------------------

Mail sent to octave-testers@bevo.che.wisc.edu goes to everyone on the
list of octave testers, which should include everyone getting the
Octave snapshots.  It is appropriate whenever you wish your mail to be
seen by all the testers.  This would include announcements of any
kind, notices of intent to implement a specific enhancement (to
coordinate with other people on the list), etc.  Before sending
something to octave-testers, ask yourself if what you are about to
send would be something you would care to see show up in your mailbox
if it was sent by someone else.

Do *not* send any questions about the snapshots or patches specific to
the snapshots to bug-octave@bevo.wisc.che.edu.  Nobody there will have
any idea what you are talking about and it will just cause confusion.


Bug reports
-----------

Send bug reports to octave-maintainers@bevo.che.wisc.edu.

Note that since no testing is done on the snapshots, and snapshots may
even be made when Octave is in an inconsistent state, it may not be
unusual for an occasional snapshot to have a very obvious bug, such as
failure to compile on *any* machine.  It is likely that such bugs will
be fixed by the next snapshot, so it really isn't necessary to report
them unless they persist over more than one snapshot.

Missing files should always be reported, since they usually mean there
is a problem with the snapshot-generating process and we won't know
about them unless someone tells us.

Bugs which are non-obvious, such as failure to compile on only a
specific machine, a new machine dependent or obscure bug (particularly
one not detected by the testsuite), etc. should be reported when you
discover them, or have a suggested patch to fix them.


FORMAT FOR PATCHES
------------------

If you have a fix for a bug, or an enhancement to submit, send your
patch to octave-maintainers@bevo.che.wisc.edu.  Here are some simple
guidelines for submitting patches:

    o	Use "context diffs" for patches.  A typical command for
	generating context diffs is "diff -rc octave-old octave-new".

    o	Use the "minimalist approach" for patches.  That is, each patch
	should address only one particular bug, new feature, etc.  Do
	not save up many unrelated changes and submit them all in one
	big patch, since in general, the larger the patch the more
	difficult it is for us to decide if the patch is either
	correct or desirable.  And if we find something about the
	patch that needs to be corrected before it can be installed,
	we would have to reject the entire patch, which might contain
	changes which otherwise would be accepted if submitted
	separately.

    o	Submit a sample ChangeLog entry with your patch.  See the
	existing Octave ChangeLog for examples of what a ChangeLog
	entry should look like.  The emacs command ^X4A will create a
	ChangeLog entry header for you.


Thanks,

John W. Eaton
jwe@bevo.che.wisc.edu
University of Wisconsin-Madison
Department of Chemical Engineering