On Fri, Jul 27, 2007 at 11:26:22AM +0100, Manuel López-Ibáñez wrote: > Just an example. There are people that post patches in bugzilla and > they seem interested in getting them integrated but normally they > break coding style or don't have changelog or didn't even run the > testsuite. Of course, the easiest answer is to point to the "how to > contribute" webpage. I have done it too. But I must admit that it is a > poor answer. When I started, I couldn't bring myself to read all that > was required to post a proper patch.
I could. Easily. But I also knew that I was going to submit more than just one or two patches. Maybe we can figure out a simpler procedure for those who will likely submit just one or two patches, where someone volunteers to fix the formatting, write the ChangeLog entry, do the testing and anything else that needs to be done for the patch to go in. I think we should encourage people to submit changes to the FSF tree rather than keeping private trees. This would include some way of dealing with copyright assignments and disclaimers before lots of patched are contributed by people who will later be difficult to track down. For example, the Amiga GCC port (host, build and target) never made it into the FSF sources mainly because by the time the idea came up, it was just too unclear who had contributed what, making it impossible to ensure the paperwork could be done. > * Documentation to learn. GCC has a lot of documentation. But it is > mostly for reference, that is, if you forget some detail or it is > under discussion, there is plenty of documentation. "grep -B 15 -e '^name_of_fuction ' *.c" you mean. > However, there is > little aimed to teach (with examples) the steps of how to contribute. > It is like telling people to learn programming by reading the ISO C > standard. The wiki is slowly changing this, but it still needs a lot > of work. A lot is missing for people writing back ends. The recent example of GEN_INT() vs. gen_int_mode()[1] is a good one. Someone new to GCC has no chance of finding such a function other than by luck. I have already started writing a simple list of helper functions for back ends some time ago. It isn't in the Wiki simply because I didn't know what a Wiki is at the time. I'll get to it in a week or so. > Regarding this, there is a curious effect that I experienced > myself. When I started one year ago I noticed the lack of simple > howtos describing the basic things like "how to submit a patch", "how > to prepare a testcase", etc. However, as soon as I learnt how to do > it, the task of describing them for newbies felt extremely tedious. This part of the documentation is fragmented in a way such that I sometimes can't find what I'm looking for, even if I know it is there (somewhere). For example, when it comes to submitting patches, we have <URL:http://gcc.gnu.org/codingconventions.html> and <URL:http://gcc.gnu.org/contribute.html> which both say something about ChangeLog enties while neither mention the patch tracker. Another example is that both <URL:http://gcc.gnu.org/contribute.html> and <URL:http://gcc.gnu.org/install/test.html> document how to test GCC, so you have to find and read both. [1] http://gcc.gnu.org/ml/gcc-patches/2007-07/msg01051.html -- Rask Ingemann Lambertsen
