Return to README-bugs CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/README-bugs, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.