Mercurial > octave-nkf
annotate README.snapshots @ 12312:b10ea6efdc58 release-3-4-x ss-3-3-91
version is now 3.3.91
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Mon, 31 Jan 2011 08:36:58 -0500 |
| parents | 66fdc831c580 |
| children |
| rev | line source |
|---|---|
| 2330 | 1 Octave Snapshots -- general info |
| 2 | |
| 3 Snapshots are an "image" of the main Octave development tree, captured | |
| 4 at a particular random instant in time. When you use the snapshots, | |
| 5 you should be able to maintain a local copy of Octave that is | |
| 6 reasonably close to the official source tree used by the Octave | |
| 7 maintainers. | |
| 8 | |
| 9 The primary purpose of providing snapshots is to widen the group of | |
| 10 motivated developers that would like to help test, debug, and enhance | |
| 11 Octave, by providing you with access to the "latest and greatest" | |
| 12 source. This has several advantages, and several disadvantages. | |
| 13 | |
| 14 First the advantages: | |
| 15 | |
| 16 o Once we have a large base of motivated testers using the | |
| 17 snapshots, this should provide good coverage across all | |
| 18 currently supported Octave hosts and targets. If a new bug is | |
| 19 introduced in Octave due to fixing another bug or ongoing | |
| 20 development, it should become obvious much more quickly and | |
| 21 get fixed before the next general net release. This should | |
| 22 help to reduce the chances of Octave being released to the | |
| 23 general public with a major bug that went unnoticed during the | |
| 24 release cycle testing because they are machine dependent. We | |
| 25 hope to greatly improve Octave's stability and reliability by | |
| 26 involving more people and more execution environments in the | |
| 27 prerelease testing. | |
| 28 | |
| 29 o With access to the latest source, any diffs that you send to fix | |
| 30 bugs or add new features should be much easier for the Octave | |
| 31 maintainers to merge into the official source base (after | |
| 32 suitable review of course). This encourages us to merge your | |
| 33 changes quicker, while they are still "fresh". | |
| 34 | |
| 35 o Once your diffs are merged, you can obtain a new copy of Octave | |
| 36 containing your changes almost immediately. Thus you do not | |
| 37 have to maintain local copies of your changes for any longer | |
| 38 than it takes to get them merged into the official source | |
| 39 base. This encourages you to send in changes quicker. | |
| 40 | |
| 41 And the disadvantages: | |
| 42 | |
| 43 o The snapshot you get will be largely untested and of unknown | |
| 44 quality. It may fail to configure or compile. It may have | |
| 45 serious bugs. You should always keep a copy of the last known | |
| 46 working version before updating to the current snapshot, or at | |
| 47 least be able to regenerate a working version if the latest | |
| 48 snapshot is unusable in your environment for some reason. | |
| 49 | |
| 50 If a production version of Octave has a bug and a snapshot has | |
| 51 the fix, and you care about stability, you should put only the | |
| 52 fix for that particular problem into your production version. | |
| 53 Of course, if you are eager to test Octave, you can use the | |
| 54 snapshot versions in your daily work, but users who have not | |
| 55 been consulted about whether they feel like testing Octave should | |
| 56 generally have something which is at least as bug free as the | |
| 57 last released version. | |
| 58 | |
| 59 o Providing timely response to your questions, bug reports, and | |
| 60 submitted patches will require the Octave developers to | |
| 61 allocate time from an already thin time budget. Please try to | |
| 62 help us make this time as productive as possible. See the | |
| 63 section below about how to submit changes. | |
| 64 | |
| 65 | |
| 66 How to get the snapshots | |
| 67 ------------------------ | |
| 68 | |
| 69 The current plan is to provide a full snapshot every week or so. For | |
| 70 now, diffs from previous versions will not be available. The files | |
| 5041 | 71 will be available via anonymous ftp from ftp.octave.org, in the |
| 2330 | 72 directory /private/octave in the form of a tar files compressed with |
| 5041 | 73 GNU gzip. You can ftp gzip from ftp.octave.org in the directory |
| 2330 | 74 /pub/gnu. |
| 75 | |
| 76 Even though the snapshots are available in a public place, we ask that | |
|
9031
1052a66078cf
Documentation cleanup of top-level Octave directory (READMEs, INSTALL)
Rik <rdrider0-list@yahoo.com>
parents:
7088
diff
changeset
|
77 recipients not widely publicize the availability of the snapshots. |
| 2330 | 78 The motivation for this request is not to hoard them, but to avoid the |
| 79 situation where the general Octave user base naively attempts to use | |
| 80 the snapshots, has trouble with them, complains publicly, and the | |
| 81 reputation of Octave declines because of a perception of instability | |
| 82 or lack of quality control. | |
| 83 | |
| 84 | |
| 85 Octave test suite | |
| 86 ----------------- | |
| 87 | |
| 88 A test suite is distributed as an integral part of the snapshots. | |
| 89 However, to use it you will need to get a copy of the dejagnu testing | |
| 90 framework. Snapshots of dejagnu are available alongside the Octave | |
| 91 snapshots, using the same naming conventions as the Octave snapshots. | |
| 92 Once you have installed the dejagnu framework, a simple "make check" | |
| 93 in the Octave directory should be sufficient to run the tests. | |
| 94 | |
| 95 Note that the test suite is still quite limited. The test framework | |
| 96 itself might not install on your system if you have an environment | |
| 97 that is not similar to one that the Octave developers already use. | |
| 98 The tests themselves only cover a small portion of Octave features, | |
| 99 and what tests do exist for a feature are not exhaustive. New tests | |
| 100 are welcomed. | |
| 101 | |
| 102 | |
| 103 Bug reports | |
| 104 ----------- | |
| 105 | |
| 5041 | 106 Send bug reports to maintainers@octave.org. |
| 2330 | 107 |
| 108 Note that since no testing is done on the snapshots, and snapshots may | |
| 109 even be made when Octave is in an inconsistent state, it may not be | |
| 110 unusual for an occasional snapshot to have a very obvious bug, such as | |
| 111 failure to compile on *any* machine. It is likely that such bugs will | |
| 112 be fixed by the next snapshot, so it really isn't necessary to report | |
| 113 them unless they persist over more than one snapshot. | |
| 114 | |
| 115 Missing files should always be reported, since they usually mean there | |
| 116 is a problem with the snapshot-generating process and we won't know | |
| 117 about them unless someone tells us. | |
| 118 | |
| 119 Bugs which are non-obvious, such as failure to compile on only a | |
| 120 specific machine, a new machine dependent or obscure bug (particularly | |
| 121 one not detected by the testsuite), etc. should be reported when you | |
| 122 discover them, or have a suggested patch to fix them. | |
| 123 | |
| 124 | |
| 125 FORMAT FOR PATCHES | |
| 126 ------------------ | |
| 127 | |
| 128 If you have a fix for a bug, or an enhancement to submit, send your | |
| 5041 | 129 patch to maintainers@octave.org. Here are some simple guidelines for |
| 130 submitting patches: | |
| 2330 | 131 |
| 132 o Use "context diffs" for patches. A typical command for | |
| 133 generating context diffs is "diff -rc octave-old octave-new". | |
| 134 | |
| 135 o Use the "minimalist approach" for patches. That is, each patch | |
| 136 should address only one particular bug, new feature, etc. Do | |
| 137 not save up many unrelated changes and submit them all in one | |
| 138 big patch, since in general, the larger the patch the more | |
| 139 difficult it is for us to decide if the patch is either | |
| 140 correct or desirable. And if we find something about the | |
| 141 patch that needs to be corrected before it can be installed, | |
| 142 we would have to reject the entire patch, which might contain | |
| 143 changes which otherwise would be accepted if submitted | |
| 144 separately. | |
| 145 | |
| 146 o Submit a sample ChangeLog entry with your patch. See the | |
| 147 existing Octave ChangeLog for examples of what a ChangeLog | |
| 148 entry should look like. The emacs command ^X4A will create a | |
| 149 ChangeLog entry header for you. | |
| 150 | |
| 151 | |
| 152 Thanks, | |
| 153 | |
| 154 John W. Eaton | |
| 9322 | 155 jwe@octave.org |
| 7088 | 156 |
| 157 Wed, 31 Oct 2007 16:31:54 EDT | |
| 158 | |
| 159 This file was adapted from a similar document written by Fred Fish and | |
| 160 used by the GDB developers. | |
| 161 |