Make the analysis page more useful
[WebKit-https.git] / Websites / webkit.org / asking_questions.html
1 <?php
2     $title = "Asking questions on webkit-help";
3
4 $extra_head_content = <<<END
5 <style type="text/css">
6 pre .code {
7    background-color: #F2F2F2;
8 }
9
10 .right {
11   color: #080 !important;
12 }
13
14 .wrong {
15   color: #f00 !important;
16 }
17 </style>
18 END;
19 include("header.inc");
20 ?>
21
22 <h1> How to ask questions about WebKit </h1>
23
24 The following tips are for new members of any WebKit mailing list who want to get help on learning WebKit.
25 These include advice on other ways to find answers and help that go beyond the WebKit's mailing lists.
26
27 <h2> Search the archives </h2>
28
29 <p>Your question may have already been answered. Make sure you search at least webkit-help and webkit-dev archives.
30 There are two ways to query the archives: doing a web search or the <a href="http://dir.gmane.org/search.php?match=webkit">gmane archives</a>.</p>
31 <p>You can limit a web search to the mailing lists' archives by using "site:lists.webkit.org".
32 <p>Here is a small example on how to query information about 'RenderLayer' on the previous mailing lists archives:</p>
33 <ul>
34 <li><a href="http://www.google.com/search?q=site:lists.webkit.org/pipermail/webkit-dev+RenderLayer">webkit-dev entries for RenderLayer</a></li>
35 <li><a href="http://www.google.com/search?q=site:lists.webkit.org/pipermail/webkit-help+RenderLayer">webkit-help entries for RenderLayer</a></li>
36 </ul>
37
38 <h2> Be precise </h2>
39 <p>Give as many details as possible. Generic questions will likely not get a valuable answer.</p>
40
41 <p>Make sure you include at least:</p>
42 <ul>
43 <li> which port are you using: Mac, Windows, Chromium, Qt, Gtk, Wx, ...</li>
44 <li> which operating system are you using? For Linux, paste the result of <code>uname -a</code></li>
45 </ul>
46
47 <p>Depending on your issue, make also sure to include:</p>
48 <ul>
49 <li> the revision or branch used</li>
50 <li> which compiler are you using? (including the version)</li>
51 <li> the CPU used</li>
52 <li> the command invoked</li>
53 <li> the <strong>complete output</strong> of the command. Do not paste only what you think is relevant.</li>
54 <li> the expected result</li>
55 </ul>
56
57 <p>If one of these item is very long (hundreds of lines), do not paste it in the email. Instead use http://pastebin.com/
58 (or other similar services) and include the link in the email.</p>
59
60 <p>Since we cannot read your mind, the more you give us, the easier it will be for us to help you.</p>
61
62 <h2> An example of question </h2>
63
64 <p>
65 <h4 class="wrong">Wrong:</h4>
66 <p>WebKit does not compile!</p>
67 <h4 class="right">Right:</h4>
68 <p>When building Apple's port revision 34567 using <code>"Tools/Scripts/build-webkit --debug --no-svg"</code>, I get the following error:</p>
69 <code>
70 Cannot find class Foobar.
71 </code>
72 <p>(You can find the complete output here: <a href="http://pastebin.com/foobar">http://pastebin.com/foobar</a>).
73
74 I have looked at the archives and the commits but did not find any solution. Does anyone know what could be the issue and whether this has been fixed?
75 </p>
76
77 <h2> Usual questions and answers </h2>
78
79 <p>There are some questions that appear regularly on the mailing list. We have included the answers here for your convenience.</p>
80
81 <h3> Does WebKit support Foo? </h3>
82
83 <p>The most reliable way to answer it is by looking at the source code. WebKit development is fast
84 paced. Often the requested feature is already implemented although it has
85 not been widely used yet. Bear in mind that sometimes the level of
86 supports between different ports is not the same.</p>
87 <p>The following links are also useful:</p>
88 <ul>
89 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(HTML)">Wikipedia comparison of the layout engines: HTML support</a><br></li>
90 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(XML)">Wikipedia comparison of the layout engines: XML support</a><br></li>
91 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Cascading_Style_Sheets)">Wikipedia comparison of the layout engines: CSS support</a><br></li>
92 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Document_Object_Model)">Wikipedia comparison of the layout engines: DOM support</a><br></li>
93 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(HTML_5)">Wikipedia comparison of the layout engines: HTML5 support</a><br></li>
94 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(ECMAScript)">Wikipedia comparison of the layout engines: ECMAScript support</a><br></li>
95 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Scalable_Vector_Graphics)">Wikipedia comparison of the layout engines: SVG support</a><br></li>
96 <li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Non-standard_HTML)">Wikipedia comparison of the layout engines: non standard HTML support</a><br></li>
97 </ul>
98
99 <h3> I want to port WebKit to a new platform </h3>
100
101 <p>As a starting point, first check <a href="http://trac.webkit.org/wiki/SuccessfulPortHowTo">the successful port how to page</a>.</p>
102
103 <p>Granted, it's not complete, so feel free to contribute. Try to find a port similar to what you are targeting and use it
104 as a basis, instead of writing everything from scratch. While working on your port, you may find that you wished the page had 
105 mentioned something. If so, please modify the page and add it.</p>
106
107 <h3> How does bar work? </h3>
108
109 <p>The best way to answer this is to use your debugger. Set a break point where you want to investigate and get a stack
110 trace. Then, you will see which functions call your code.</p>
111
112 <h2> Things to remember when you ask a question </h2>
113
114 <ul>
115 <li> We offer our help on a voluntary basis so you can't expect us to be
116 100% at your disposal. Be patient. No need to insist on the urgency. Asking urgently
117 for an answer usually does not get you the answer faster.</li>
118
119 <li> We love to grow our community, and thus we like to help beginners. After all,
120 every expert was a beginner at some point in his/her lifetime. However, nobody likes
121 <strong>lazy</strong> beginners. Thus, if you face a problem, try to analyze and
122 solve it yourself first <strong>before</strong> asking for help.</li>
123
124 <li> WebKit is a big project with a huge code base, so you must be willing
125 to spend your time and effort on learning the source code. Remember,
126 you can not become a Grand Master just by skimming some chess learning
127 books.</li>
128
129 <li>Last but not least, there are often complaints that WebKit code
130 is not easy to understand. Well, this is your chance to contribute! We
131 have started some helping pages on this, just check out:
132 <a href="http://trac.webkit.org/wiki/WikiStart#GettingAroundtheWebKitSourceCode">our wiki's page on how to get around the code</a></li>
133 </ul>
134
135 <p>Do not hesitate to fill the wiki page with new information which will help
136 others to learn!</p>
137
138 <?php
139 include("footer.inc");
140 ?>