-Here are the guidelines for being an Emacs pretester.
-If you would like to do this, say so, and I'll add you to
-the pretest list.
-
-
- Information for Emacs Pretesters
-
-The purpose of Emacs pretesting is to verify that the new Emacs
-distribution, about to be released, works properly on your system *with
-no change whatever*, when installed following the precise
-recommendations that come with the Emacs distribution.
-
-Here are some guidelines on how to do pretesting so as to make it
-helpful. All of them follow from common sense together with the
-nature of the purpose and the situation.
-
-Please save this file, and reread it when a new series of pretests
-starts.
-
-* Get the pretest from gnu/emacs/emacs-MM.NN.tar.gz and
-gnu/emacs/leim-MM.NN.tar.gz on alpha.gnu.org.
-
-* After a few days of testing, if there are no problems, please report
-that Emacs works for you and what configuration you are testing it on.
-
-* If you want to communicate with other pretesters, send mail to
-emacs-pretesters@gnu.org. I don't use that mailing list when I send
-to you because I've found that mailing lists tend to amplify random
-noise into long discussions or even arguments, and that can waste a
-lot of time. But when you have a reason to ask other pretesters for
-help, you can do it that way.
-
-* It is absolutely vital that you tell me about even the smallest
-change or departure from the standard sources and procedure.
-
-Otherwise, you are not testing the same program that I asked you to
-test. Testing a different program is usually of no use whatever. It
-can even cause trouble if you fail to tell me that you tested some
-other program instead of what I am about to release. I might think
-that Emacs works, when in fact it has not even been tried, and might
-have a glaring fault.
-
-* Don't use a site-load.el file or a site-init.el file when you pretest.
-Using either of those files means you are not testing Emacs as a typical
-site would use it.
-
-Actually, it does no harm to test Emacs with such customizations *as
-well as* testing it "out of the box". Anything you do that could find
-a bug is useful, as long as you make sure I know exactly what you did.
-The important point is that testing with local changes is no
-substitute for testing Emacs exactly as it is distributed.
-
-* Even changing the compilation options counts as a change in the
-program. The Emacs sources specify which compilation options to use.
-Some of them are specified in makefiles, and some in machine-specific
-configuration files. They also give you ways to override this--but if
-you do, then you are not testing what ordinary users will do.
-Therefore, when pretesting, it is vital to test with the default
-compilation options.
-
-(Testing with a different set of options can be useful *in addition*,
-but not *instead of* the default options.)
-
-* The machine and system configuration files of Emacs are parts of
-Emacs. So when you test Emacs, you need to do it with the
-configuration files that come with Emacs.
-
-If Emacs does not come with configuration files for a certain machine,
-and you test it with configuration files that don't come with Emacs,
-this is effectively changing Emacs. Because the crucial fact about
-the planned release is that, without changes, it doesn't work on that
-machine.
-
-To make Emacs work on that machine, I would need to install new
-configuration files. That is not out of the question, since it is
-safe--it certainly won't break any other machines that already work.
-But you will have to rush me the legal papers to give the FSF
-permission to use such a large piece of text.
-
-* Look in the etc/MACHINES file.
-
-The etc/MACHINES file says which configuration files to use for your
-machine, so use the ones that are recommended. If you guess, you might
-guess wrong and encounter spurious difficulties. What's more, if you
-don't follow etc/MACHINES then you aren't helping to test that its
-recommendations are valid.
-
-The etc/MACHINES file may describe other things that you need to do
-to make Emacs work on your machine. If so, you should follow these
-recommendations also, for the same reason.
-
-* Send your problem reports to emacs-pretest-bug@gnu.org, not
-bug-gnu-emacs.
-
-Sometimes I won't know what to do about a system-dependent issue, and
-I may need people to tell me what happens if you try a certain thing
-on a certain system. When this happens, I'll send out a query.
-
-* Don't delay sending information.
-
-When you test on a system and encounter no problems, please tell me
-about it right away. That way, I will know that someone has tested
-Emacs on that kind of system.
-
-Please don't wait for several days "to see if it really works before
-you say anything." Tell me right away that Emacs seems basically to
-work; then, if you notice a problem a few days later, tell me
-immediately about that when you see it.
-
-It is okay if you double check things before reporting a problem, such
-as to see if you can easily fix it. But don't wait very long. A good
-rule to use in pretesting is always to tell me about every problem on
-the same day you encounter it, even if that means you can't find a
-solution before you report the problem.
-
-I'd much rather hear about a problem today and a solution tomorrow
-than get both of them tomorrow at the same time.
-
-* Make each bug report self-contained.
-
-If you refer back to another message, whether from you or from someone
-else, then it will be necessary for anyone who wants to investigate
-the bug to find the other message. This may be difficult, it is
-probably time-consuming.
-
-To help me save time, simply copy the relevant parts of any previous
-messages into your own bug report.
-
-In particular, if I ask you for more information because a bug report
-was incomplete, it is best to send me the *entire* collection of
-relevant information, all together. If you send just the additional
-information, that makes me do extra work. There is even a risk that
-I won't remember what question you are sending me the answer to.
-
-* When you encounter a bug that manifests itself as a Lisp error,
-try setting debug-on-error to t and making the bug happen again.
-Then you will get a Lisp backtrace. Including that in your bug report
-is very useful.
-
-* Debugging optimized code is possible, if you compile with GCC, but
-in some cases the optimized code can be confusing. If you are not
-accustomed to that, recompile Emacs without -O. One way to do this is
-
- make clean
- make CFLAGS=-g
-
-* If you use X windows, it is a good idea to run Emacs under GDB (or
-some other suitable debugger) *all the time*, at least while
-pretesting.
-
-Then, when Emacs crashes, you will be able to debug the live process,
-not just a core dump. The `pr' command defined in src/.gdbinit is very
-useful in this case for examining Lisp_Object values as they would
-appear in Lisp.
-
-If you can't use `pr' because Emacs has got a fault already, or
-because you have only a core dump, you can use `xtype' to look at the
-type of a value, and then choose one of the other commands `xsymbol',
-`xstring', `xcons', `xvector' and so on to examine the contents.
-
-I myself *always* run Emacs under GDB so that I can debug conveniently
-if the occasion arises.
-
-* To get Lisp-level backtrace information within GDB,
-look for stack frames that call Ffuncall. Select them one by one in GDB
-and type this:
-
- p *args
- pr
-
-This will print the name of the Lisp function called by that level
-of function calling.
-
-By printing the remaining elements of args, you can see the argument
-values. Here's how to print the first argument:
-
- p args[1]
- pr
-
-If you do not have a live process, you can use xtype and the other
-x... commands such as xsymbol to get such information, albeit less
-conveniently.
-
-* Even with a live process, these x... commands are useful for
-examining the fields in a buffer, window, process, frame or marker.
-Here's an example using concepts explained in the node "Value History"
-of the GDB manual to print the variable frame from this line in
-xmenu.c:
-
- buf.frame_or_window = Fcons (frame, prefix);
-
-First, use these commands:
-
- cd src
- gdb emacs
- b xmenu.c:1209
- r -q
-
-Then type C-x 5 2 to create a new frame, and it hits the breakpoint:
-
- (gdb) p frame
- $1 = 1077872640
- (gdb) xtype
- Lisp_Vectorlike
- PVEC_FRAME
- (gdb) xframe
- $2 = (struct frame *) 0x3f0800
- (gdb) p *$
- $3 = {
- size = 536871989,
- next = 0x366240,
- name = 809661752,
- [...]
- }
- (gdb) p $3->name
- $4 = 809661752
-
-Now we can use `pr' to print the name of the frame:
-
- (gdb) pr
- "emacs@steenrod.math.nwu.edu"
-
-* The Emacs C code heavily uses macros defined in lisp.h. So suppose
-we want the address of the l-value expression near the bottom of
-`kbd_buffer_store_event' from keyboard.c:
-
- XVECTOR (kbd_buffer_frame_or_window)->contents[kbd_store_ptr
- - kbd_buffer]
- = event->frame_or_window);
-
-XVECTOR is a macro, and therefore GDB does not know about it.
-GDB cannot evaluate p XVECTOR (kbd_buffer_frame_or_window).
-
-However, you can use the xvector command in GDB to get the same
-result. Here is how:
-
- (gdb) p kbd_buffer_frame_or_window
- $1 = 1078005760
- (gdb) xvector
- $2 = (struct Lisp_Vector *) 0x411000
- 0
- (gdb) p $->contents[kbd_store_ptr - kbd_buffer]
- $3 = 1077872640
- (gdb) p &$
- $4 = (int *) 0x411008
-
-* Here's a related example of macros and the GDB `define' command.
-There are many Lisp vectors such as `recent_keys', which contains the
-last 100 keystrokes. We can print this Lisp vector
-
-p recent_keys
-pr
-
-But this may be inconvenient, since `recent_keys' is much more verbose
-than `C-h l'. We might want to print only the last 10 elements of
-this vector. `recent_keys' is updated in keyboard.c by the command
-
- XVECTOR (recent_keys)->contents[recent_keys_index] = c;
-
-So we define a GDB command `xvector-elts', so the last 10 keystrokes
-are printed by
-
- xvector-elts recent_keys recent_keys_index 10
-
-where you can define xvector-elts as follows:
-
- define xvector-elts
- set $i = 0
- p $arg0
- xvector
- set $foo = $
- while $i < $arg2
- p $foo->contents[$arg1-($i++)]
- pr
- end
- document xvector-elts
- Prints a range of elements of a Lisp vector.
- xvector-elts v n i
- prints `i' elements of the vector `v' ending at the index `n'.
- end
-
-* To debug what happens while preloading and dumping Emacs,
-do `gdb temacs' and start it with `r -batch -l loadup dump'.
-
-If temacs actually succeeds when running under GDB in this way, do not
-try to run the dumped Emacs, because it was dumped with the GDB
-breakpoints in it.
-
-* If you encounter X protocol errors, try evaluating (x-synchronize t).
-That puts Emacs into synchronous mode, where each Xlib call checks for
-errors before it returns. This mode is much slower, but when you get
-an error, you will see exactly which call really caused the error.
-
-* If the symptom of the bug is that Emacs fails to respond, don't
-assume Emacs is `hung'--it may instead be in an infinite loop. To
-find out which, make the problem happen under GDB and stop Emacs once
-it is not responding. (If Emacs is using X Windows directly, you can
-stop Emacs by typing C-z at the GDB job.) Then try stepping with
-`step'. If Emacs is hung, the `step' command won't return. If it is
-looping, `step' will return.
-
-If this shows Emacs is hung in a system call, stop it again and
-examine the arguments of the call. In your bug report, state exactly
-where in the source the system call is, and what the arguments are.
-
-If Emacs is in an infinite loop, please determine where the loop
-starts and ends. The easiest way to do this is to use the GDB command
-`finish'. Each time you use it, Emacs resumes execution until it
-exits one stack frame. Keep typing `finish' until it doesn't
-return--that means the infinite loop is in the stack frame which you
-just tried to finish.
-
-Stop Emacs again, and use `finish' repeatedly again until you get back
-to that frame. Then use `next' to step through that frame. By
-stepping, you will see where the loop starts and ends. Also please
-examine the data being used in the loop and try to determine why the
-loop does not exit when it should. Include all of this information in
-your bug report.
-
-* If certain operations in Emacs are slower than they used to be, here
-is some advice for how to find out why.
-
-Stop Emacs repeatedly during the slow operation, and make a backtrace
-each time. Compare the backtraces looking for a pattern--a specific
-function that shows up more often than you'd expect.
-
-If you don't see a pattern in the C backtraces, get some Lisp
-backtrace information by looking at Ffuncall frames (see above), and
-again look for a pattern.
-
-When using X, you can stop Emacs at any time by typing C-z at GDB.
-When not using X, you can do this with C-g.
-
-* Configure tries to figure out what kind of system you have by
-compiling and linking programs which calls various functions and looks
-at whether that succeeds. The file config.log contains any messages
-produced by compilers while running configure, to aid debugging if
-configure makes a mistake. But note that config.cache reads:
-
-# Giving --cache-file=/dev/null disables caching, for debugging configure.
-
-or more simply,
-
-rm config.cache
-./configure
-
-* Always be precise when talking about changes you have made. Show
-things rather than describing them. Use exact filenames (relative to
-the main directory of the distribution), not partial ones. For
-example, say "I changed Makefile" rather than "I changed the
-makefile". Instead of saying "I defined the MUMBLE macro", send a
-diff.
-
-* Always use `diff -c' to make diffs. If you don't include context, it
-may be hard for me to figure out where you propose to make the
-changes. So I might have to ignore your patch.
-
-* When you write a fix, keep in mind that I can't install a change
-that *might* break other systems without the risk that it will fail to
-work and therefore require an additional cycle of pretesting.
-
-People often suggest fixing a problem by changing config.h or
-src/ymakefile or even src/Makefile to do something special that a
-particular system needs. Sometimes it is totally obvious that such
-changes would break Emacs for almost all users. I can't possibly make
-a change like that. All I can do is send it back to you and ask you
-to find a fix that is safe to install.
-
-Sometimes people send fixes that *might* be an improvement in
-general--but it is hard to be sure of this. I can install such
-changes some of the time, but not during pretest, when I am trying to
-get a new version to work reliably as quickly as possible.
-
-The safest changes for me to install are changes to the s- and m-
-files. At least I know those can't affect most systems.
-
-Another safe kind of change is one that uses a conditional to make
-sure it will apply only to a particular kind of system. Ordinarily,
-that is a bad way to solve a problem, and I would want to find a
-cleaner alternative. But the virtue of safety can make it superior at
-pretest time.
-
-* Don't try changing Emacs *in any way* unless it fails to work unchanged.
-
-* Don't even suggest changes to add features or make something
-cleaner. Every change I install could introduce a bug, so I won't
-install a change during pretest unless I see it is *necessary*.
-
-* If you would like to suggest changes for purposes other than fixing
-user-visible bugs, don't wait till pretest time. Instead, send them
-after I have made a release that proves to be stable. Then I can give
-your suggestions proper consideration. If you send them at pretest
-time, I will have to defer them till later, and that might mean I
-forget all about them.
-
-* In some cases, if you don't follow these guidelines, your
-information might still be useful, but I might have to do more work to
-make use of it. Unfortunately, I am so far behind in my work that I
-just can't keep up unless you help me to do it efficiently.
-\f
-Some suggestions for debugging on MS Windows:
-
- Marc Fleischeuers, Geoff Voelker and Andrew Innes
-
-To debug emacs with Microsoft Visual C++, you either start emacs from
-the debugger or attach the debugger to a running emacs process. To
-start emacs from the debugger, you can use the file bin/debug.bat. The
-Microsoft Developer studio will start and under Project, Settings,
-Debug, General you can set the command-line arguments and emacs'
-startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal and
-other functions that you want to examine. Run the program (Build,
-Start debug). Emacs will start and the debugger will take control as
-soon as a breakpoint is hit.
-
-You can also attach the debugger to an already running emacs process.
-To do this, start up the Microsoft Developer studio and select Build,
-Start debug, Attach to process. Choose the emacs process from the
-list. Send a break to the running process (Debug, Break) and you will
-find that execution is halted somewhere in user32.dll. Open the stack
-trace window and go up the stack to w32_msg_pump. Now you can set
-breakpoints in emacs (Edit, Breakpoints). Continue the running emacs
-process (Debug, Step out) and control will return to emacs, until a
-breakpoint is hit.
-
-To examine the contents of a lisp variable, you can use the function
-'debug_print'. Right-click on a variable, select QuickWatch, and
-place 'debug_print(' and ')' around the expression. Press
-'Recalculate' and the output is sent to the 'Debug' pane in the Output
-window. If emacs was started from the debugger, a console window was
-opened at emacs' startup; this console window also shows the output of
-'debug_print'. It is also possible to keep appropriately masked and
-typecast lisp symbols in the Watch window, this is more convenient
-when steeping though the code. For instance, on entering
-apply_lambda, you can watch (struct Lisp_Symbol *) (0xfffffff &
-args[0]).
-
-\f
-Local Variables:
-mode: text
-End:
+Here are the guidelines for being an Emacs pretester.
+If you would like to do this, say so, and I'll add you to
+the pretest list.
+
+
+ Information for Emacs Pretesters
+
+The purpose of Emacs pretesting is to verify that the new Emacs
+distribution, about to be released, works properly on your system *with
+no change whatever*, when installed following the precise
+recommendations that come with the Emacs distribution.
+
+Here are some guidelines on how to do pretesting so as to make it
+helpful. All of them follow from common sense together with the
+nature of the purpose and the situation.
+
+Please save this file, and reread it when a new series of pretests
+starts.
+
+* Get the pretest from gnu/emacs/pretest/emacs-MM.0.NN.tar.gz
+on alpha.gnu.org.
+
+* After a few days of testing, if there are no problems, please report
+that Emacs works for you and what configuration you are testing it on.
+
+* If you want to communicate with other pretesters, send mail to
+emacs-pretesters@gnu.org. I don't use that mailing list when I send
+to you because I've found that mailing lists tend to amplify random
+noise into long discussions or even arguments, and that can waste a
+lot of time. But when you have a reason to ask other pretesters for
+help, you can do it that way.
+
+* It is absolutely vital that you report even the smallest change or
+departure from the standard sources and procedure.
+
+Otherwise, you are not testing the same program that we asked you to
+test. Testing a different program is usually of no use whatever. It
+can even cause trouble, if you fail to tell us that you tested some
+other program instead of what we are about to release. We might think
+that Emacs works, when in fact it has not even been tried, and might
+have a glaring fault.
+
+* Don't use a site-load.el file or a site-init.el file when you pretest.
+Using either of those files means you are not testing Emacs as a typical
+site would use it.
+
+Actually, it does no harm to test Emacs with such customizations *as
+well as* testing it "out of the box". Anything you do that could find
+a bug is useful, as long as you make sure we know exactly what you
+did. The important point is that testing with local changes is no
+substitute for testing Emacs exactly as it is distributed.
+
+* Even changing the compilation options counts as a change in the
+program. The Emacs sources specify which compilation options to use.
+Some of them are specified in makefiles, and some in machine-specific
+configuration files. They also give you ways to override this--but if
+you do, then you are not testing what ordinary users will do.
+Therefore, when pretesting, it is vital to test with the default
+compilation options.
+
+(Testing with a different set of options can be useful *in addition*,
+but not *instead of* the default options.)
+
+* The machine and system configuration files of Emacs are parts of
+Emacs. So when you test Emacs, you need to do it with the
+configuration files that come with Emacs.
+
+If Emacs does not come with configuration files for a certain machine,
+and you test it with configuration files that don't come with Emacs,
+this is effectively changing Emacs. Because the crucial fact about
+the planned release is that, without changes, it doesn't work on that
+machine.
+
+To make Emacs work on that machine, we would need to install new
+configuration files. That is not out of the question, since it is
+safe--it certainly won't break any other machines that already work.
+But you will have to rush in the legal papers to give the FSF
+permission to use such a large piece of text.
+
+* Look in the etc/MACHINES file.
+
+The etc/MACHINES file says which configuration files to use for your
+machine, so use the ones that are recommended. If you guess, you might
+guess wrong and encounter spurious difficulties. What's more, if you
+don't follow etc/MACHINES then you aren't helping to test that its
+recommendations are valid.
+
+The etc/MACHINES file may describe other things that you need to do
+to make Emacs work on your machine. If so, you should follow these
+recommendations also, for the same reason.
+
+* Send your problem reports to bug-gnu-emacs@gnu.org.
+
+Sometimes we won't know what to do about a system-dependent issue, and
+we may need people to say what happens if you try a certain thing on a
+certain system. When this happens, we'll send out a query.
+
+* Don't delay sending information.
+
+When you test on a system and encounter no problems, please report it
+right away. That way, we will know that someone has tested Emacs on
+that kind of system.
+
+Please don't wait for several days "to see if it really works before
+you say anything." Tell us right away that Emacs seems basically to
+work; then, if you notice a problem a few days later, tell us
+immediately about that when you see it.
+
+It is okay if you double check things before reporting a problem, such
+as to see if you can easily fix it. But don't wait very long. A good
+rule to use in pretesting is always to report every problem on the
+same day you encounter it, even if that means you can't find a
+solution before you report the problem.
+
+I'd much rather hear about a problem today and a solution tomorrow
+than get both of them tomorrow at the same time.
+
+* Make each bug report self-contained.
+
+If you refer back to another message, whether from you or from someone
+else, then it will be necessary for anyone who wants to investigate
+the bug to find the other message. This may be difficult, it is
+probably time-consuming.
+
+To help save our time, simply copy the relevant parts of any previous
+messages into your own bug report.
+
+In particular, if we ask you for more information because a bug report
+was incomplete, it is best to send me the *entire* collection of
+relevant information, all together. If you send just the additional
+information, that makes extra work for us. There is even a risk that
+we won't remember what question you are sending the answer to.
+
+* When you encounter a bug that manifests itself as a Lisp error,
+try setting debug-on-error to t and making the bug happen again.
+Then you will get a Lisp backtrace. Including that in your bug report
+is very useful.
+
+* For advice on debugging, see etc/DEBUG.
+
+* Debugging optimized code is possible, if you compile with GCC, but
+in some cases the optimized code can be confusing. If you are not
+accustomed to that, recompile Emacs without -O. One way to do this is
+
+ make clean
+ make CFLAGS=-g
+
+* Configure tries to figure out what kind of system you have by
+compiling and linking programs which calls various functions and looks
+at whether that succeeds. The file config.log contains any messages
+produced by compilers while running configure, to aid debugging if
+configure makes a mistake. But note that config.cache reads:
+
+# Giving --cache-file=/dev/null disables caching, for debugging configure.
+
+or more simply,
+
+rm config.cache
+./configure
+
+* Don't try changing Emacs *in any way* during pretest unless it fails
+to work unchanged.
+
+* Always be precise when talking about changes you have made. Show
+things rather than describing them. Use exact filenames (relative to
+the main directory of the distribution), not partial ones. For
+example, say "I changed Makefile" rather than "I changed the
+makefile". Instead of saying "I defined the MUMBLE macro", send a
+diff.
+
+* Always use `diff -c' to make diffs. If you don't include context, it
+may be hard for us to figure out where you propose to make the
+changes. So we might ignore your patch.
+
+* When you write a fix, keep in mind that we can't install a change
+that *might* break other systems without the risk that it will fail to
+work and therefore require an additional cycle of pretesting.
+
+People often suggest fixing a problem by changing config.h or
+src/Makefile to do something special that a particular system needs.
+Sometimes it is totally obvious that such changes would break Emacs
+for almost all users. We can't possibly make a change like that. All
+we can do is ask you to find a fix that is safe to install.
+
+Sometimes people send fixes that *might* be an improvement in
+general--but it is hard to be sure of this. I can install such
+changes some of the time, but not during pretest, when I am trying to
+get a new version to work reliably as quickly as possible.
+
+The safest changes for us to install are changes to the s- and m-
+files. At least those can't break other systems.
+
+Another safe kind of change is one that uses a conditional to make
+sure it will apply only to a particular kind of system. Ordinarily,
+that is a bad way to solve a problem, and I would want to find a
+cleaner alternative. But the virtue of safety can make it superior at
+pretest time.
+
+* Don't suggest changes during pretest to add features or make
+something cleaner. Every change risks introducing a bug, so I won't
+install a change during pretest unless it is *necessary*.
+
+* If you would like to suggest changes for purposes other than fixing
+user-visible bugs, don't wait till pretest time. Instead, send them
+after we have made a release that proves to be stable. That is the
+easiest time to consider such suggestions. If you send them at
+pretest time, we will have to defer them till later, and that might
+mean we forget all about them.
+
+* In some cases, if you don't follow these guidelines, your
+information might still be useful, but we would have to do more work
+to make use of it. That might cause it to fall by the wayside.
+\f
+Local Variables:
+mode: text
+End:
+
HCoop / bpt / emacs.git / blobdiff