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