gcc/README-bugs

   1 The purpose of GCC pretesting is to verify that the new GCC
   2 distribution, about to be released, works properly on your system *with
   3 no change whatever*, when installed following the precise
   4 recommendations that come with the distribution.
   5
   6 Here are some guidelines on how to do pretesting so as to make it
   7 helpful.  All of them follow from common sense together with the
   8 nature of the purpose and the situation.
   9
  10 * It is absolutely vital that you mention even the smallest change or
  11 departure from the standard sources and installation procedure.
  12
  13 Otherwise, you are not testing the same program that I wrote.  Testing
  14 a different program is usually of no use whatever.  It can even cause
  15 trouble if you fail to tell me that you tested some other program
  16 instead of what I know as GCC.  I might think that GCC works, when in
  17 fact it has not been properly tried, and might have a glaring fault.
  18
  19 * Even changing the compilation options counts as a change in the
  20 program.  The GCC sources specify which compilation options to use.
  21 Some of them are specified in makefiles, and some in machine-specific
  22 configuration files.
  23
  24 You have ways to override this--but if you do, then you are not
  25 testing what ordinary users will do.  Therefore, when pretesting, it
  26 is vital to test with the default compilation options.
  27
  28 (It is okay to test with nonstandard options as well as testing with
  29 the standard ones.)
  30
  31 * The machine and system configuration files of GCC are parts of
  32 GCC.  So when you test GCC, you need to do it with the
  33 configuration files that come with GCC.
  34
  35 If GCC does not come with configuration files for a certain machine,
  36 and you test it with configuration files that don't come with GCC,
  37 this is effectively changing GCC.  Because the crucial fact about
  38 the planned release is that, without changes, it doesn't work on that
  39 machine.
  40
  41 To make GCC work on that machine, I would need to install new
  42 configuration files.  That is not out of the question, since it is
  43 safe--it certainly won't break any other machines that already work.
  44 But you will have to rush me the legal papers to give the FSF
  45 permission to use a large piece of text.
  46
  47 * Look for recommendations for your system.
  48
  49 You can find these recommendations in the Installation node of the
  50 manual, and in the file INSTALL.  (These two files have the same text.)
  51
  52 These files say which configuration name to use for your machine, so
  53 use the ones that are recommended.  If you guess, you might guess
  54 wrong and encounter spurious difficulties.  What's more, if you don't
  55 follow the recommendations then you aren't helping to test that its
  56 recommendations are valid.
  57
  58 These files may describe other things that you need to do to make GCC
  59 work on your machine.  If so, you should follow these recommendations
  60 also, for the same reason.
  61
  62 Also look at the Trouble chapter of the manual for items that
  63 pertain to your machine.
  64
  65 * Don't delay sending information.
  66
  67 When you find a problem, please double check it if you can do so
  68 quickly.  But don't spend a long time double-checking.  A good rule is
  69 always to tell me about every problem on the same day you encounter
  70 it, even if that means you can't find a solution before you report the
  71 problem.
  72
  73 I'd much rather hear about a problem today and a solution tomorrow
  74 than get both of them tomorrow at the same time.
  75
  76 * Make each bug report self-contained.
  77
  78 If you refer back to another message, whether from you or from someone
  79 else, then it will be necessary for anyone who wants to investigate
  80 the bug to find the other message.  This may be difficult, it is
  81 probably time-consuming.
  82
  83 To help me save time, simply copy the relevant parts of any previous
  84 messages into your own bug report.
  85
  86 In particular, if I ask you for more information because a bug report
  87 was incomplete, it is best to send me the *entire* collection of
  88 relevant information, all together.  If you send just the additional
  89 information, that makes me do extra work.  There is even a risk that
  90 I won't remember what question you are sending me the answer to.
  91
  92 * Always be precise when talking about changes you have made.  Show
  93 things rather than describing them.  Use exact filenames (relative to
  94 the main directory of the distribution), not partial ones.  For
  95 example, say "I changed Makefile" rather than "I changed the
  96 makefile".  Instead of saying "I defined the MUMBLE macro", send a
  97 diff that shows your change.
  98
  99 * Always use `diff -c' to make diffs.  If you don't include context,
 100 it may be hard for me to figure out where you propose to make the
 101 changes.  I might have to ignore your patch because I can't tell what
 102 it means.
 103
 104 * When you write a fix, keep in mind that I can't install a change
 105 that would break other systems.
 106
 107 People often suggest fixing a problem by changing machine-independent
 108 files such as toplev.c to do something special that a particular
 109 system needs.  Sometimes it is totally obvious that such changes would
 110 break GCC for almost all users.  I can't possibly make a change like
 111 that.  All I can do is send it back to you and ask you to find a fix
 112 that is safe to install.
 113
 114 Sometimes people send fixes that *might* be an improvement in
 115 general--but it is hard to be sure of this.  I can install such
 116 changes some of the time, but not during pretest, when I am trying to
 117 get a new version to work reliably as quickly as possible.
 118
 119 The safest changes for me to install are changes to the configuration
 120 files for a particular machine.  At least I know those can't create
 121 bugs on other machines.
 122
 123 * Don't try changing GCC unless it fails to work if you don't change it.
 124
 125 * Don't even suggest changes that would only make GCC cleaner.
 126 Every change I install could introduce a bug, so I won't install
 127 a change unless I see it is necessary.
 128
 129 * If you would like to suggest changes for purposes other than fixing
 130 serious bugs, don't wait till pretest time.  Instead, send them just
 131 after I make a release.  That's the best time for me to install them.
 132
 133 * In some cases, if you don't follow these guidelines, your
 134 information might still be useful, but I might have to do more work to
 135 make use of it.  Unfortunately, I am so far behind in my work that I
 136 just can't get the job done unless you help me to do it efficiently.
 137
 138
 139                                 Thank you
 140                                    rms
 141 \f
 142 Local Variables:
 143 mode: text
 144 End: