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