Author: sebor
Date: Mon Aug 1 18:03:26 2005
New Revision: 226921
URL: http://svn.apache.org/viewcvs?rev=226921&view=rev
Log:
2005-08-01 Martin Sebor <[EMAIL PROTECTED]>
STDCXX-9:
* bugs.html (href): Added documentation of the process of dealing
with bugs and other issues in the project.
Added:
incubator/stdcxx/site/bugs.html
Added: incubator/stdcxx/site/bugs.html
URL:
http://svn.apache.org/viewcvs/incubator/stdcxx/site/bugs.html?rev=226921&view=auto
==============================================================================
--- incubator/stdcxx/site/bugs.html (added)
+++ incubator/stdcxx/site/bugs.html Mon Aug 1 18:03:26 2005
@@ -0,0 +1,396 @@
+<!DOCTYPE HTML PUBLIC
+ "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>Bugs in Apache C++ Standard Library</title>
+ <link type="text/css" href="basic.css" rel="stylesheet">
+ <link rel="shortcut icon" href="">
+ </head>
+
+ <div id="top">
+ <!-- breadcrumbs -->
+ <div class="breadtrail">
+ <a href="http://incubator.apache.org/";>Incubator</a> >
+ <a href="http://incubator.apache.org/stdcxx/";>stdcxx</a> >
+ <a href="http://incubator.apache.org/stdcxx/bugs.html";>Bugs</a>
+ </div>
+ <div class="header">
+ <div class="grouplogo">
+ <a href="http://incubator.apache.org/";>
+ <img class="logoImage"
+ alt="Apache Incubator"
+ title="Apache Incubator"
+ src="images/incubator_logo.gif"
+ border="0" >
+ </a>
+ </div>
+ <div class="projectlogo">
+ <a href="http://incubator.apache.org/stdcxx/";>
+ <img class="logoImage"
+ alt="STDCXX - Apache C++ Standard Library"
+ title="STDCXX - Apache C++ Standard Library"
+ src="images/stdcxx.gif"
+ border="0">
+ </a>
+ </div>
+ <div class="searchbox">
+ <form action="http://www.google.com/search";
+ method="get"
+ class="roundtopsmall">
+ <input value="apache.org" name="sitesearch" type="hidden">
+ <input value="" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+ </form>
+ </div>
+ <ul id="tabs">
+ <li class="current">
+ <a class="base-selected" href="bugs.html">Bugs</a>
+ </li>
+ </ul>
+ </div>
+ </div> <!-- top -->
+
+ <div id="main">
+ <div id="publishedStrip">
+ Last Modified: $Date$
+ </div>
+ <div class="breadtrail">
+
+ </div>
+
+ <!-- left hand navigation -->
+ <div id="menu">
+ <div class="menupage">
+
+ <div class="menuitem">
+ <a title="" href="index.html">
+ stdcxx
+ </a>
+ </div>
+ <div class="menuitem">
+ <a title="" href="http://incubator.apache.org/projects/stdcxx.html";>
+ Status
+ </a>
+ </div>
+ <div class="menuitem">
+ <a title="" href="#">
+ Download
+ </a>
+ </div>
+ <div class="menuitem">
+ <a title=""
href="http://svn.apache.org/repos/asf/incubator/stdcxx/trunk/etc/config/README";>
+ README
+ </a>
+ </div>
+ <div class="menuitem">
+ <a title="" href="http://www.apache.org/licenses/LICENSE-2.0";>
+ License
+ </a>
+ </div>
+
+ <div id="menu_selected_1.1"
+ class="selectedmenuitemgroup"
+ style="display: block;">
+ <div class="menupage">
+ <div class="menupagetitle">Bugs</div>
+ </div>
+ </div>
+
+ <div class="menuitem">
+ <a title=""
href="http://svn.apache.org/repos/asf/incubator/stdcxx/trunk/doc/stdlibref/";>
+ Class Reference
+ </a>
+ </div>
+ <div class="menuitem">
+ <a title=""
href="http://svn.apache.org/repos/asf/incubator/stdcxx/trunk/doc/stdlibug/";>
+ User Guide
+ </a>
+ </div>
+ <div class="menuitem">
+ <a title="" href="#">
+ Design and Style Document
+ </a>
+ </div>
+
+ </div> <!-- menupage -->
+ <div id="roundbottom">
+ <img style="display: none" class="corner" height="15" width="15"
+ alt="" src="images/rc-b-l-15-1body-2menu-3menu.png">
+ </div>
+ </div> <!-- menu -->
+ </div> <!-- main -->
+
+ <!--start main content-->
+ <div id="content">
+ <h1>Bugs in Apache C++ Standard Library</h1>
+ <div id="minitoc-area">
+ <ul class="minitoc">
+ <li><a href="#bug_definition">What Is a Bug</a></li>
+ <li><a href="#before_reporting">Before Reporting a Bug</a></li>
+ <li><a href="#report">Reporting a Bug</a></li>
+ <li><a href="#patches">Submitting Patches</a></li>
+ <li><a href="#patch_format">Patch Format</a></li>
+ </ul>
+ </div>
+
+ <a name="bug_definition"></a>
+ <h2 class="boxed">What Is a Bug</h2>
+ <div class="section">
+ <p>
+
+<a class ="external"
+href="http://en.wikipedia.org/wiki/";>Wikipedia</a>, the free online
+encyclopedia, defines a bug as follows:
+
+ </p>
+ <p>
+
+<i>A computer bug is an error, flaw, mistake, failure, or fault in a
+computer program that prevents it from working correctly or produces
+an incorrect result.</i>
+
+ </p>
+ </div>
+
+ <a name="before_reporting"></a>
+ <h2 class="boxed">Before Reporting a Bug</h2>
+ <div class="section">
+ <p>
+ <ol>
+ <li>
+ <p>
+
+If you have discovered a bug in stdcxx and would like to report it to
+the development team, please be sure to first check the project's <a
+href="http://issues.apache.org/jira/browse/STDCXX";>bug tracking
+database</a> to see whether the bug has already been reported and, if
+so, what its status is. If the bug has not been reported yet, follow
+the instructions on <a href="report">Reporting a Bug</a>
+below. Otherwise, feel free to add a comment to the issue in the bug
+tracking database if you think it might help resolve it more quickly
+(for example, if you have a smaller or better test case).
+
+ </p>
+ </li>
+ <li>
+ <p>
+
+If you think but aren't 100% sure that you have discovered a bug in
+the source code of the project, please consult a reliable <a
+href="index.html#references">reference</a> on the subject first and
+confirm that the behavior you are experiencing is, in fact, a bug and
+not a feature. If even after reading the relevant references you are
+still not sure, you should send an email to <a
+href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>
+and ask. If the problem is indeed a bug, go back to step 1.
+
+ </p>
+ </li>
+ <li>
+ <p>
+
+If you have a suggestion for a change or an addition to the interface
+or the behavior of this implementation of the library that you would
+like to propose to the development team (e.g., an enhancement
+request), please make sure that the change is not in conflict with the
+requirements of the C++ Standard. You can get an electronic copy of
+the <a class ="external"
+href="http://webstore.ansi.org/ansidocstore/product.asp?sku=INCITS%2FISO%2FIEC+14882%2D2003";>C++
+Standard</a> from the ANSI <a class="external"
+href="http://webstore.ansi.org/ansidocstore";>eStandards store</a>. If
+your request is not in conflict with any requirements of the C++
+standard, open a request for Improvement or New Feature to the bug
+tracking database (see the stdcxx bug tracking database <a
+class="external"
+href="http://www.atlassian.com/software/jira/docs/";>documentation</a>
+for the available <a class="external"
+href="http://www.atlassian.com/software/jira/docs/latest/issues.html#IssueTypes";>issue
+types</a>).
+
+ </p>
+ </li>
+ </ol>
+ </p>
+ </div> <!-- section -->
+
+ <a name="report"></a>
+ <h2 class="boxed">Reporting a Bug</h2>
+ <div class="section">
+ <p>
+
+To report a new bug in this implementation of the C++ Standard Library
+or the accompanying utilities or example programs, or a problem in any
+other part of the stdcxx project such as its documentation or Web
+pages, open an issue in the project's <a
+href="http://issues.apache.org/jira/browse/STDCXX";>bug tracking
+database</a>. Make sure you assign the bug the appropriate
+component. For example, if the bug has to do with the formatting of
+numbers using iostreams, the likely components will be
+22. Localization, or 27. Input/Output.
+
+ </p>
+ <p>
+
+When reporting a bug in the implementation of the library, make sure
+to demonstrate the problem in a small (50 lines of code or less) C++
+program that does not depend on any third party libraries (system
+libraries excluded). In addition to the program, make sure to include
+the details of the environment in which the bug can be reproduces,
+including the full command line used to compile, link, and run the
+program, and the output of each of the mentioned stages, specifically
+any compiler or linker diagnostics, and, if applicable, the output of
+the program itself. When the problem manisfests itself in the form of
+an abnormal program termination (e.g., crash), it helps to include the
+full stack trace at the crash site. To demonstrate incorrect
+behavior, use the <code>assert()</code> macro to assert any
+postconditions. Refer to existing bug reports (such as <a
+href="http://issues.apache.org/jira/browse/STDCXX-2";>STDCXX-2</a>) for
+examples. By following this advice you will increase the chances that
+the bug will be resolved quickly.
+
+ </p>
+ </div>
+
+ <a name="patches"></a>
+ <h2 class="boxed">Submitting Patches</h2>
+ <div class="section">
+ <p>
+
+If you would like to submit a patch for a bug that you or someone else
+reported, you can do so in two ways:
+
+ </p>
+ <ol>
+ <li>
+
+Post the patch to the project development mailing list, <a
+href="mailto:[email protected]";>[email protected]</a>.
The
+subject line of the email should start with the string [PATCH],
+followed by a brief description of the patch. An easy way to come up
+with a good description for the patch subject line is to simply copy
+the Summary from the bug report. Be sure to also include a reference
+to the bug (preferably in the form of a link to the original bug
+report).
+
+ </li>
+ <li>
+
+Add the patch to the bug report in the form of a comment (when the
+patch is just a few lines of text), or in the form of an attachment to
+the issue.
+
+ </li>
+ </ol>
+ <p>
+
+If you would like to submit a patch for a bug that doesn't have a
+corresponding issue in the bug tracking database, you should start by
+creating a small test case to demonstrate the problem first. It's not
+uncommon for this exercise to expose an error in the usage of the
+library rather than in the library implementation itself. Once you've
+isolated the bug to a small test case and filed an issue in the bug
+tracking database you can update the issue with the proposed patch.
+
+ </p>
+ <p>
+
+If you would like to submit a patch with an improvement to the project
+(such as an optimization tweak), post the patch along with a detailed
+description as well as before and after data showing the improvement
+to the project development mailing list, <a
+href="mailto:[email protected]";>[email protected]</a>.
+
+ </p>
+ <p>
+
+In all cases, make sure your patch follows the expected <a
+href="#patch_format">Patch Format</a> described below.
+
+ </p>
+ </div>
+
+ <a name="patch_format"></a>
+ <h2 class="boxed">Patch Format</h2>
+ <div class="section">
+ <p>
+
+Every patch should include the following information:
+
+ </p>
+ <ol>
+ <li>
+
+Detailed explanation of the change. It should be obvious from reading
+this narrative alone (i.e., without looking at the source code) what
+the change does and why.
+
+ </li>
+ <li>
+ <p>
+
+Change Log entry. The format of Change Log entries follows the
+established GNU Change Log convention. <a class="external"
+href="http://www.gnu.org/software/emacs/";>Emacs</a> users can take
+advantage of the <a class="external"
+href="http://www.gnu.org/software/emacs/manual/html_node/Change-Log.html#Change%20Log";>add-change-log-entry</a>
+command.
+
+ </p>
+ <p>
+
+Each Change Log entry consists of a reference to the <i>issue key</i>
+representing the corresponding issue in the bug tracking database (if
+applicable), the name of the submitter, the submission date, and a
+description of all changes arranged by files and symbols modified by
+the change.
+
+ </p>
+ <p>
+
+The format of the issue key is especially important in order for the
+the bug tracking database to be able to update the issue in the bug
+tracking database with information about the change. The issue key
+format is <code>STDCXX-NNN</code> where the <code>NNN</code> part is
+the issue number (for example, <a
+href="http://issues.apache.org/jira/browse/STDCXX-2";><code>STDCXX-2</code></a>).
+
+ </p>
+ </li>
+ <li>
+
+The diff between the most recent versions of the file being modified
+and the modified version. The diff should be in a format suitable for
+processing by the standard POSIX <a class="external"
+href="http://www.opengroup.org/onlinepubs/009695399/utilities/patch.html";><code>patch</code></a>
+utility, or in the <a class="external"
+href="http://www.gnu.org/software/diffutils/manual/html_node/Unified-Format.html#Unified%20Format";>Unified
+format</a> produced by the <a class="external"
+href="http://subversion.tigris.org/";>Subversion</a> <a
+class="external"
+href="http://svnbook.red-bean.com/en/1.1/ch03s05.html#svn-ch-3-sect-5.3.2";><code>svn
+diff</code></a> command by default as well as by the GNU <a
+class="external"
+href="http://www.gnu.org/software/diffutils/diffutils.html";><code>diff</code></a>
+utility and understood by GNU <a class="external"
+href="http://www.gnu.org/software/patch/patch.html";><code>patch</code></a>.
+
+ </li>
+ </ol>
+ </div>
+
+ <!-- End main content -->
+
+ <div class="clearboth"> </div>
+ </div>
+ <div id="footer">
+ <!--+
+ |start bottomstrip
+ +-->
+ <div class="copyright">
+ Copyright © 2005 The Apache Software Foundation.
+ </div>
+ </div>
+ </body>
+</html>
