Author: kkolinko
Date: Fri Jun 18 02:45:37 2010
New Revision: 955819
URL: http://svn.apache.org/viewvc?rev=955819&view=rev
Log:
Updated the bug reporting docs:
Rewrote the "not support forum" section.
Rewrote the bug reporting section, added subsections there.
Modified:
tomcat/site/trunk/docs/bugreport.html
tomcat/site/trunk/xdocs/bugreport.xml
Modified: tomcat/site/trunk/docs/bugreport.html
URL:
http://svn.apache.org/viewvc/tomcat/site/trunk/docs/bugreport.html?rev=955819&r1=955818&r2=955819&view=diff
==============================================================================
--- tomcat/site/trunk/docs/bugreport.html (original)
+++ tomcat/site/trunk/docs/bugreport.html Fri Jun 18 02:45:37 2010
@@ -193,10 +193,12 @@
<ul>
<li>
<a href="#Before_you_report_a_bug">Before you report a bug</a>
-</li>
+<ol>
<li>
<a href="#Bugzilla_is_not_a_support_forum">Bugzilla is not a support forum</a>
</li>
+</ol>
+</li>
<li>
<a href="#Resources_to_help_resolve_Apache_Tomcat_problems">Resources to help
resolve Apache Tomcat problems</a>
<ol>
@@ -224,6 +226,12 @@
<a href="#Reporting_Apache_Tomcat_bugs">Reporting Apache Tomcat bugs</a>
<ol>
<li>
+<a href="#How_to_write_a_bug_report">How to write a bug report</a>
+</li>
+<li>
+<a href="#Patches_and_enhancement_requests">Patches and enhancement
requests</a>
+</li>
+<li>
<a href="#Security_Issues">Security Issues</a>
</li>
</ol>
@@ -264,27 +272,20 @@ wide variety of reasons, and almost all
<p>Many bugs reported end up not being a bug in the Apache Tomcat code, but are
due to misconfiguration, problems caused by installed applications, the
-operating system, etc.
+operating system, etc.</p>
+
<ul>
<b>Before reporting a bug please make every effort to resolve the problem
yourself.</b>
</ul>
-The remainder of this document points you toward resources you can use to
+
+<p>The remainder of this document points you toward resources you can use to
resolve the problem you are having.
</p>
-</blockquote>
-</p>
-</td>
-</tr>
-<tr>
-<td>
-<br/>
-</td>
-</tr>
-</table>
-<table border="0" cellspacing="0" cellpadding="2" width="100%">
+
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr>
-<td bgcolor="#525D76">
+<td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Bugzilla is not a support forum">
<!--()-->
@@ -297,12 +298,36 @@ resolve the problem you are having.
</tr>
<tr>
<td>
-<p>
<blockquote>
-<p>Support questions should not be sent to Bugzilla. If you cannot diagnose
-your problem, or if the problem is in your configuration, use the
-<a href="lists.html">mailing lists</a>.
-</p>
+ <p>Bugzilla is a tool to track bug reports and feature requests. It is used
+ to organize work on Apache Tomcat projects, so that such issues are not
+ forgotten and to document how they were resolved.
+ </p>
+
+ <p>Bugzilla is not a place to ask questions on how to configure your own
+ system, or how to interpret some error message that you do not understand.
+ </p>
+
+ <p>If you have any such questions, please use available
+ <a href="findhelp.html">support</a> channels. The most popular one is the
+ <b>users</b> <a href="lists.html">mailing list</a>.
+ </p>
+
+ <p>When you have gathered enough information to diagnose your problem,
+ and it is indeed a bug that <em>can</em> be fixed in Apache Tomcat, feel
+ free to create (or reopen) a Bugzilla issue for it. If you discussed the
+ issue on a mailing list, you can add a link to your discussion that can be
+ found in <a href="lists.html">mailing list</a> archives.
+ </p>
+ </blockquote>
+</td>
+</tr>
+<tr>
+<td>
+<br/>
+</td>
+</tr>
+</table>
</blockquote>
</p>
</td>
@@ -353,7 +378,8 @@ problem you are having before reporting
<li>
<b>Documentation</b> – Review the documentation for the version
of Apache Tomcat that you are using. The problem that you are
- facing may already be addressed in the docs.</li>
+ facing may already be addressed in the docs. Note, that documentation
+ is searchable.</li>
<li>
<b>Logs</b> – The logs which Apache Tomcat generates can be a valuable
resource when trying to diagnose a problem. Please review them.
@@ -390,7 +416,7 @@ problem you are having before reporting
<td>
<blockquote>
<p>It is very likely you are not the first to run into a problem.
- Others may have already found a solution. The <b>tomcat-user</b>,
+ Others may have already found a solution. The <b>tomcat-users</b>,
<b>taglibs-user</b> or <b>tomcat-dev</b> list archives may contain
discussions which will help you resolve the problem.
</p>
@@ -544,6 +570,7 @@ problem you are having before reporting
<ul>
<li>
+ <a
href="http://tomcat.apache.org/tomcat-7.0-doc/changelog.html";>Tomcat 7.0</a>,
<a
href="http://tomcat.apache.org/tomcat-6.0-doc/changelog.html";>Tomcat 6.0</a>,
<a
href="http://tomcat.apache.org/tomcat-5.5-doc/changelog.html";>Tomcat 5.5</a>
</li>
@@ -561,6 +588,7 @@ problem you are having before reporting
<ul>
<li>
+ <a
href="http://svn.apache.org/repos/asf/tomcat/trunk/webapps/docs/changelog.xml";>Tomcat
7.0 (trunk)</a>,
<a
href="http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml";>Tomcat
6.0</a>,
<a
href="http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml";>Tomcat
5.5</a>
</li>
@@ -607,77 +635,6 @@ problem you are having before reporting
<p>Please make sure the problem is a bug in Apache Tomcat and not a
bug in your web application.</p>
-<p>Please provide as much information as possible. It is
-very hard to fix a bug if the person looking into the problem cannot
-reproduce it. Here is a listing of information which should be included:</p>
-<ul>
- <li>Environment details:
- <ul>
- <li>
-<b>Version</b> – Apache Tomcat version, if from a nightly build,
- version and date of build. Please not only select the version from a
- list, but also repeat it in the text of your bug report.</li>
- <li>
-<b>Platform</b> and <b>OS</b> – Hardware platform and operating system
- Tomcat is running on.</li>
- <li>
-<b>Java version</b> – Vendor and version of your Java Runtime
- Environment used to run Tomcat.</li>
- </ul>
- </li>
- <li>Configuration:
- <ul>
- <li>
-<b>Component</b> – Apache Tomcat component which has the bug.
- If you do not know, just guess.</li>
- <li>
-<b>Web Server</b> – Web Server and version, Apache Tomcat Connector
- and version.</li>
- <li>
-<b>Configuration</b> – Attach configuration files if they would
- help to track down the bug.</li>
- </ul>
- </li>
- <li>Evidences:
- <ul>
- <li>
-<b>Log file excerpts</b> – Review your logs files, reproduce the bug
- with debugging enabled in your Apache Tomcat configuration. Then submit
- any relevant sections of the log which help to document the bug.</li>
- <li>
-<b>Stack Traces</b> – Any stack traces generated by the bug.</li>
- </ul>
- </li>
- <li>
-<b>Example</b> – Example configuration files or web applications which
- demonstrate the bug. When submitting an example which reproduces the bug,
- please try to make it as simple as possible.</li>
- <li>
-<b>Bug Fix Patch</b> – A patch that fixes the issue, if you know
- how to fix it.</li>
- <li>
-<b>Miscellaneous</b> – Any other information that you feel will help
- to track down the problem. For example other Java API's and versions being
- used with Apache Tomcat.</li>
-</ul>
-
-<p>
-Enhancements for Tomcat are submitted using the same procedure, but in the
-<b>Severity</b> field you will select the value "<code>enhancement</code>".
-</p>
-
-<p>
-Any patches are welcome, but we prefer the ones that use the
-<a href="http://en.wikipedia.org/wiki/Diff#Unified_format";>Unified Diff</a>
-format. Those can be generated using <code>diff -u</code> command, or, if you
-have obtained the Tomcat sources from the <a href="svn.html">Subversion
-repository</a>, using the <code>svn diff</code> command.
-For more information on Subversion and how to use it, see
-<a href="http://svnbook.red-bean.com/";> the Subversion Book.</a>
-When providing a patch, please mention to which version of the sources it
-applies.
-</p>
-
<p>
Report an Apache Tomcat 7 bug
<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%207";>
@@ -698,7 +655,139 @@ Report an Apache Taglibs bug
<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Taglibs";>
here</a>.<br/>
</p>
-<p/>
+
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+<tr>
+<td bgcolor="#828DA6">
+<font color="#ffffff" face="arial,helvetica,sanserif">
+<a name="How to write a bug report">
+<!--()-->
+</a>
+<a name="How_to_write_a_bug_report">
+<strong>How to write a bug report</strong>
+</a>
+</font>
+</td>
+</tr>
+<tr>
+<td>
+<blockquote>
+ <p>Please provide as much information as possible. It is
+ very hard to fix a bug if the person looking into the problem cannot
+ reproduce it.
+ </p>
+
+ <p>See also
+ <a
href="https://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html";>Bug
Writing Guidelines</a>.
+ </p>
+
+ <p>You can include the following information in your bug report:</p>
+ <ul>
+ <li>Attribution:
+ <ul>
+ <li>
+<b>Version</b> – Apache Tomcat version.<br/>
+ Please not only select it from the list, but also mention it in
+ your text.</li>
+ <li>
+<b>Component</b> – The component which has the bug.<br/>
+ If you do not know, just guess.</li>
+ </ul>
+ </li>
+ <li>Environment details:
+ <ul>
+ <li>
+<b>Platform</b> and <b>OS</b> – Hardware platform and
+ operating system Tomcat is running on.</li>
+ <li>
+<b>Java version</b> – Vendor and version of your Java
+ Runtime Environment used to run Tomcat.</li>
+ <li>
+<b>Web Server</b> – Web Server and version, Apache Tomcat
+ Connector that you are using, if you are running Tomcat behind
+ another web server, such as
+ <a href="http://httpd.apache.org/";>Apache HTTP Server</a>.</li>
+ </ul>
+ </li>
+ <li>Configuration:
+ <ul>
+ <li>Attach configuration files if they would help to track down the
+ bug.</li>
+ </ul>
+ </li>
+ <li>Evidences:
+ <ul>
+ <li>Log file excerpts, stack traces, messages</li>
+ </ul>
+ </li>
+ </ul>
+
+ <p>Please describe how to reproduce your problem on a clean Tomcat
+ installation. It is easier to reproduce an issue if you can prepare a
+ sample simple web application that demonstrates it.</p>
+ </blockquote>
+</td>
+</tr>
+<tr>
+<td>
+<br/>
+</td>
+</tr>
+</table>
+
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+<tr>
+<td bgcolor="#828DA6">
+<font color="#ffffff" face="arial,helvetica,sanserif">
+<a name="Patches and enhancement requests">
+<!--()-->
+</a>
+<a name="Patches_and_enhancement_requests">
+<strong>Patches and enhancement requests</strong>
+</a>
+</font>
+</td>
+</tr>
+<tr>
+<td>
+<blockquote>
+ <p>Enhancement requests for Tomcat are submitted using the same procedure
+ as bug reports, but in the <b>Severity</b> field you will select the value
+ "<em>enhancement</em>".
+ </p>
+
+ <p>To propose a patch, attach it to a Bugzilla issue. Any patches are
welcome,
+ but we prefer the ones that use the
+ <a href="http://en.wikipedia.org/wiki/Diff#Unified_format";>Unified Diff</a>
+ format. Those can be generated using <code>diff -u</code> command or
+ <code>svn diff</code> command.
+ </p>
+
+ <p>When providing a patch, please mention to which version of the sources it
+ applies.</p>
+
+ <p>The following references may be useful:</p>
+ <ul>
+ <li>Tomcat <a href="svn.html">SVN repository structure</a>
+</li>
+ <li>BUILDING.txt in your version of Tomcat</li>
+ <li>General <a
href="http://www.apache.org/dev/version-control.html#anon-svn";>Apache
+ guidance for Subversion</a>
+</li>
+ <li>
+<a href="http://svnbook.red-bean.com/";>the Subversion Book</a>
+</li>
+ </ul>
+ </blockquote>
+</td>
+</tr>
+<tr>
+<td>
+<br/>
+</td>
+</tr>
+</table>
+
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr>
<td bgcolor="#828DA6">
Modified: tomcat/site/trunk/xdocs/bugreport.xml
URL:
http://svn.apache.org/viewvc/tomcat/site/trunk/xdocs/bugreport.xml?rev=955819&r1=955818&r2=955819&view=diff
==============================================================================
--- tomcat/site/trunk/xdocs/bugreport.xml (original)
+++ tomcat/site/trunk/xdocs/bugreport.xml Fri Jun 18 02:45:37 2010
@@ -21,23 +21,42 @@ wide variety of reasons, and almost all
<p>Many bugs reported end up not being a bug in the Apache Tomcat code, but are
due to misconfiguration, problems caused by installed applications, the
-operating system, etc.
+operating system, etc.</p>
+
<ul>
<b>Before reporting a bug please make every effort to resolve the problem
yourself.</b>
</ul>
-The remainder of this document points you toward resources you can use to
+
+<p>The remainder of this document points you toward resources you can use to
resolve the problem you are having.
</p>
-</section>
-<section name="Bugzilla is not a support forum">
-<p>Support questions should not be sent to Bugzilla. If you cannot diagnose
-your problem, or if the problem is in your configuration, use the
-<a href="lists.html">mailing lists</a>.
-</p>
+ <subsection name="Bugzilla is not a support forum">
+ <p>Bugzilla is a tool to track bug reports and feature requests. It is used
+ to organize work on Apache Tomcat projects, so that such issues are not
+ forgotten and to document how they were resolved.
+ </p>
+
+ <p>Bugzilla is not a place to ask questions on how to configure your own
+ system, or how to interpret some error message that you do not understand.
+ </p>
+
+ <p>If you have any such questions, please use available
+ <a href="findhelp.html">support</a> channels. The most popular one is the
+ <b>users</b> <a href="lists.html">mailing list</a>.
+ </p>
+
+ <p>When you have gathered enough information to diagnose your problem,
+ and it is indeed a bug that <em>can</em> be fixed in Apache Tomcat, feel
+ free to create (or reopen) a Bugzilla issue for it. If you discussed the
+ issue on a mailing list, you can add a link to your discussion that can be
+ found in <a href="lists.html">mailing list</a> archives.
+ </p>
+ </subsection>
</section>
+
<section name="Resources to help resolve Apache Tomcat problems">
<p>Here are some resources you can use to help you resolve the
problem you are having before reporting a bug.</p>
@@ -46,7 +65,8 @@ problem you are having before reporting
<p>
<li><b>Documentation</b> – Review the documentation for the version
of Apache Tomcat that you are using. The problem that you are
- facing may already be addressed in the docs.</li>
+ facing may already be addressed in the docs. Note, that documentation
+ is searchable.</li>
<li><b>Logs</b> – The logs which Apache Tomcat generates can be a
valuable
resource when trying to diagnose a problem. Please review them.
You may want to enable debug output in your Apache Tomcat configuration
@@ -58,7 +78,7 @@ problem you are having before reporting
<subsection name="Apache Tomcat discussion lists">
<p>It is very likely you are not the first to run into a problem.
- Others may have already found a solution. The <b>tomcat-user</b>,
+ Others may have already found a solution. The <b>tomcat-users</b>,
<b>taglibs-user</b> or <b>tomcat-dev</b> list archives may contain
discussions which will help you resolve the problem.
</p>
@@ -106,6 +126,7 @@ problem you are having before reporting
<ul>
<li>
+ <a
href="http://tomcat.apache.org/tomcat-7.0-doc/changelog.html";>Tomcat 7.0</a>,
<a
href="http://tomcat.apache.org/tomcat-6.0-doc/changelog.html";>Tomcat 6.0</a>,
<a
href="http://tomcat.apache.org/tomcat-5.5-doc/changelog.html";>Tomcat 5.5</a>
</li>
@@ -123,6 +144,7 @@ problem you are having before reporting
<ul>
<li>
+ <a
href="http://svn.apache.org/repos/asf/tomcat/trunk/webapps/docs/changelog.xml";>Tomcat
7.0 (trunk)</a>,
<a
href="http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml";>Tomcat
6.0</a>,
<a
href="http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml";>Tomcat
5.5</a>
</li>
@@ -145,66 +167,6 @@ problem you are having before reporting
<p>Please make sure the problem is a bug in Apache Tomcat and not a
bug in your web application.</p>
-<p>Please provide as much information as possible. It is
-very hard to fix a bug if the person looking into the problem cannot
-reproduce it. Here is a listing of information which should be included:</p>
-<ul>
- <li>Environment details:
- <ul>
- <li><b>Version</b> – Apache Tomcat version, if from a nightly build,
- version and date of build. Please not only select the version from a
- list, but also repeat it in the text of your bug report.</li>
- <li><b>Platform</b> and <b>OS</b> – Hardware platform and operating
system
- Tomcat is running on.</li>
- <li><b>Java version</b> – Vendor and version of your Java Runtime
- Environment used to run Tomcat.</li>
- </ul>
- </li>
- <li>Configuration:
- <ul>
- <li><b>Component</b> – Apache Tomcat component which has the bug.
- If you do not know, just guess.</li>
- <li><b>Web Server</b> – Web Server and version, Apache Tomcat
Connector
- and version.</li>
- <li><b>Configuration</b> – Attach configuration files if they would
- help to track down the bug.</li>
- </ul>
- </li>
- <li>Evidences:
- <ul>
- <li><b>Log file excerpts</b> – Review your logs files, reproduce
the bug
- with debugging enabled in your Apache Tomcat configuration. Then submit
- any relevant sections of the log which help to document the bug.</li>
- <li><b>Stack Traces</b> – Any stack traces generated by the
bug.</li>
- </ul>
- </li>
- <li><b>Example</b> – Example configuration files or web applications
which
- demonstrate the bug. When submitting an example which reproduces the bug,
- please try to make it as simple as possible.</li>
- <li><b>Bug Fix Patch</b> – A patch that fixes the issue, if you know
- how to fix it.</li>
- <li><b>Miscellaneous</b> – Any other information that you feel will help
- to track down the problem. For example other Java API's and versions being
- used with Apache Tomcat.</li>
-</ul>
-
-<p>
-Enhancements for Tomcat are submitted using the same procedure, but in the
-<b>Severity</b> field you will select the value "<code>enhancement</code>".
-</p>
-
-<p>
-Any patches are welcome, but we prefer the ones that use the
-<a href="http://en.wikipedia.org/wiki/Diff#Unified_format";>Unified Diff</a>
-format. Those can be generated using <code>diff -u</code> command, or, if you
-have obtained the Tomcat sources from the <a href="svn.html">Subversion
-repository</a>, using the <code>svn diff</code> command.
-For more information on Subversion and how to use it, see
-<a href="http://svnbook.red-bean.com/";> the Subversion Book.</a>
-When providing a patch, please mention to which version of the sources it
-applies.
-</p>
-
<p>
Report an Apache Tomcat 7 bug
<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%207";>
@@ -225,7 +187,84 @@ Report an Apache Taglibs bug
<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Taglibs";>
here</a>.<br />
</p>
-<p></p>
+
+ <subsection name="How to write a bug report">
+ <p>Please provide as much information as possible. It is
+ very hard to fix a bug if the person looking into the problem cannot
+ reproduce it.
+ </p>
+
+ <p>See also
+ <a
href="https://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html";>Bug
Writing Guidelines</a>.
+ </p>
+
+ <p>You can include the following information in your bug report:</p>
+ <ul>
+ <li>Attribution:
+ <ul>
+ <li><b>Version</b> – Apache Tomcat version.<br />
+ Please not only select it from the list, but also mention it in
+ your text.</li>
+ <li><b>Component</b> – The component which has the bug.<br />
+ If you do not know, just guess.</li>
+ </ul>
+ </li>
+ <li>Environment details:
+ <ul>
+ <li><b>Platform</b> and <b>OS</b> – Hardware platform and
+ operating system Tomcat is running on.</li>
+ <li><b>Java version</b> – Vendor and version of your Java
+ Runtime Environment used to run Tomcat.</li>
+ <li><b>Web Server</b> – Web Server and version, Apache Tomcat
+ Connector that you are using, if you are running Tomcat behind
+ another web server, such as
+ <a href="http://httpd.apache.org/";>Apache HTTP Server</a>.</li>
+ </ul>
+ </li>
+ <li>Configuration:
+ <ul>
+ <li>Attach configuration files if they would help to track down the
+ bug.</li>
+ </ul>
+ </li>
+ <li>Evidences:
+ <ul>
+ <li>Log file excerpts, stack traces, messages</li>
+ </ul>
+ </li>
+ </ul>
+
+ <p>Please describe how to reproduce your problem on a clean Tomcat
+ installation. It is easier to reproduce an issue if you can prepare a
+ sample simple web application that demonstrates it.</p>
+ </subsection>
+
+ <subsection name="Patches and enhancement requests">
+ <p>Enhancement requests for Tomcat are submitted using the same procedure
+ as bug reports, but in the <b>Severity</b> field you will select the value
+ "<em>enhancement</em>".
+ </p>
+
+ <p>To propose a patch, attach it to a Bugzilla issue. Any patches are
welcome,
+ but we prefer the ones that use the
+ <a href="http://en.wikipedia.org/wiki/Diff#Unified_format";>Unified Diff</a>
+ format. Those can be generated using <code>diff -u</code> command or
+ <code>svn diff</code> command.
+ </p>
+
+ <p>When providing a patch, please mention to which version of the sources it
+ applies.</p>
+
+ <p>The following references may be useful:</p>
+ <ul>
+ <li>Tomcat <a href="svn.html">SVN repository structure</a></li>
+ <li>BUILDING.txt in your version of Tomcat</li>
+ <li>General <a
href="http://www.apache.org/dev/version-control.html#anon-svn";>Apache
+ guidance for Subversion</a></li>
+ <li><a href="http://svnbook.red-bean.com/";>the Subversion Book</a></li>
+ </ul>
+ </subsection>
+
<subsection name="Security Issues">
<p>Security-related bugs are of special concern. If you have a verified
security bug to report please neither post it
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
