freebsd-src/contrib/gcc/README-bugs

The purpose of GCC pretesting is to verify that the new GCC
distribution, about to be released, works properly on your system *with
no change whatever*, when installed following the precise
recommendations that come with the 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.

* It is absolutely vital that you mention even the smallest change or
departure from the standard sources and installation procedure.

Otherwise, you are not testing the same program that I wrote.  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 know as GCC.  I might think that GCC works, when in
fact it has not been properly tried, and might have a glaring fault.

* Even changing the compilation options counts as a change in the
program.  The GCC sources specify which compilation options to use.
Some of them are specified in makefiles, and some in machine-specific
configuration files.

You have 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.

(It is okay to test with nonstandard options as well as testing with
the standard ones.)

* The machine and system configuration files of GCC are parts of
GCC.  So when you test GCC, you need to do it with the
configuration files that come with GCC.

If GCC does not come with configuration files for a certain machine,
and you test it with configuration files that don't come with GCC,
this is effectively changing GCC.  Because the crucial fact about
the planned release is that, without changes, it doesn't work on that
machine.

To make GCC 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 a large piece of text.

* Look for recommendations for your system.

You can find these recommendations in the Installation node of the
manual, and in the file INSTALL.  (These two files have the same text.)

These files say which configuration name 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 the recommendations then you aren't helping to test that its
recommendations are valid.

These files may describe other things that you need to do to make GCC
work on your machine.  If so, you should follow these recommendations
also, for the same reason.

Also look at the Trouble chapter of the manual for items that
pertain to your machine.

* Don't delay sending information.

When you find a problem, please double check it if you can do so
quickly.  But don't spend a long time double-checking.  A good rule 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.

* 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 that shows your change.

* 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.  I might have to ignore your patch because I can't tell what
it means.

* When you write a fix, keep in mind that I can't install a change
that would break other systems.

People often suggest fixing a problem by changing machine-independent
files such as toplev.c to do something special that a particular
system needs.  Sometimes it is totally obvious that such changes would
break GCC 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 configuration
files for a particular machine.  At least I know those can't create
bugs on other machines.

* Don't try changing GCC unless it fails to work if you don't change it.

* Don't even suggest changes that would only make GCC cleaner.
Every change I install could introduce a bug, so I won't install
a change unless I see it is necessary.

* If you would like to suggest changes for purposes other than fixing
serious bugs, don't wait till pretest time.  Instead, send them just
after I make a release.  That's the best time for me to install 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 get the job done unless you help me to do it efficiently.


				Thank you
				   rms

Local Variables:
mode: text
End: