[Emacs-diffs] Changes to emacs/admin/emacs-pretesters

[Richard M . Stallman]

Index: emacs/admin/emacs-pretesters
diff -c emacs/admin/emacs-pretesters:1.3 emacs/admin/emacs-pretesters:1.4
*** emacs/admin/emacs-pretesters:1.3    Mon Sep  1 15:44:58 2003
--- emacs/admin/emacs-pretesters        Sat Jun  4 10:23:55 2005
***************
*** 30,42 ****
  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.
  
--- 30,42 ----
  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.
  
***************
*** 46,53 ****
  
  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
--- 46,53 ----
  
  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
***************
*** 71,80 ****
  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.
--- 71,80 ----
  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.
***************
*** 92,116 ****
  * Send your problem reports to address@hidden, 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
--- 92,116 ----
  * Send your problem reports to address@hidden, not
  bug-gnu-emacs.
  
! 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
***************
*** 123,142 ****
  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
--- 123,144 ----
  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
***************
*** 144,336 ****
      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
-     "address@hidden"
- 
- * 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
--- 146,151 ----
***************
*** 344,349 ****
--- 159,167 ----
  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
***************
*** 352,378 ****
  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,
--- 170,196 ----
  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/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.  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,
***************
*** 380,439 ****
  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.
! 
! 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]).
! 
  
  Local Variables:
  mode: text
--- 198,217 ----
  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.
  
  Local Variables:
  mode: text