You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stdcxx.apache.org by se...@apache.org on 2007/07/29 02:31:24 UTC
svn commit: r560651 - /incubator/stdcxx/site/bugs.html
Author: sebor
Date: Sat Jul 28 17:31:23 2007
New Revision: 560651
URL: http://svn.apache.org/viewvc?view=rev&rev=560651
Log:
2007-07-28 Martin Sebor <se...@roguewave.com>
* bugs.html: Added a new section on Requesting an Enhancement.
Extended the section on reporting bugs.
Added more detail to the expected patch format, including before
and after performance timings and/or size changes.
Replaced references to the "bug tracking database" with "issue
tracking database."
Added links to Jira issue types and corrected a broken link to
the Emacs manual.
Modified:
incubator/stdcxx/site/bugs.html
Modified: incubator/stdcxx/site/bugs.html
URL: http://svn.apache.org/viewvc/incubator/stdcxx/site/bugs.html?view=diff&rev=560651&r1=560650&r2=560651
==============================================================================
--- incubator/stdcxx/site/bugs.html (original)
+++ incubator/stdcxx/site/bugs.html Sat Jul 28 17:31:23 2007
@@ -137,7 +137,8 @@
<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="#external">External Bugs</a></li>
- <li><a href="#report">Reporting a Bug</a></li>
+ <li><a href="#bugreport">Reporting a Bug</a></li>
+ <li><a href="#enhancement_request">Requesting an Enhancement</a></li>
<li><a href="#patches">Submitting Patches</a></li>
<li><a href="#patch_format">Patch Format</a></li>
<li><a href="#new_files">New Files</a></li>
@@ -173,11 +174,11 @@
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
+href="http://issues.apache.org/jira/browse/STDCXX">issue 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
+the instructions on <a href="#report">Reporting a Bug</a>
+below. Otherwise, feel free to add a comment to the issue in the issue
tracking database if you think it might help resolve it more quickly
(for example, if you have a smaller or better test case).
@@ -210,8 +211,8 @@
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
+standard, open a request for Improvement or New Feature to the issue
+tracking database (see the stdcxx issue tracking database <a
class="external"
href="http://www.atlassian.com/software/jira/docs/">documentation</a>
for the available <a class="external"
@@ -232,7 +233,7 @@
We track bugs in compilers, operating systems, and other software
external to the Apache C++ Standard Library that affect the correct
behavior or performance of the library or programs that use it in the
-bug tracking database along with other bugs. These bug reports are
+issue tracking database along with other bugs. These bug reports are
often quite useful when porting the project to new versions of the
software. See the table below for filters with predefined searches for
bugs relevant to specific compilers, operating systems, and/or common
@@ -337,6 +338,7 @@
</div> <!-- section -->
<a name="report"></a>
+ <a name="bugreport"></a>
<h2 class="boxed">Reporting a Bug</h2>
<div class="section">
<p>
@@ -345,17 +347,21 @@
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.
+href="http://issues.apache.org/jira/browse/STDCXX">issue tracking
+database</a> and choose <i>Bug</i> for the <a class="external"
+href="http://www.atlassian.com/software/jira/docs/latest/issues.html#IssueTypes">Issue
+Type</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 <a
+href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?component=12310134">22. Localization</a>,
+or <a
+href="http://issues.apache.org/jira/secure/IssueNavigator.jspa?component=12310139">27. Input/Output</a>.
</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++
+When reporting a bug in this implementation of the library, be 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,
@@ -374,6 +380,21 @@
</p>
</div>
+ <a name="enhancement_request"></a>
+ <h2 class="boxed">Requesting an Enhancement</h2>
+ <div class="section">
+ <p>
+
+The process for requesting enhancements and new features in stdcxx is
+essentially the same as the process for <a href="#bugreport">Reporting
+a bug</a> except that instead choosing <i>Bug</i> as the Issue Type
+you will choose either <i>Improvevement</i> when requesting an
+enhancement to an existing feature, or <i>New Feature</i> when
+requesting an entire new feature.
+
+ </p>
+ </div>
+
<a name="patches"></a>
<h2 class="boxed">Submitting Patches</h2>
<div class="section">
@@ -396,10 +417,11 @@
href="mailto:stdcxx-dev@incubator.apache.org">stdcxx-dev@incubator.apache.org</a>. The
subject line of the email should start with the string [PATCH],
followed by a brief description of the patch and the issue number from
-the bug tracking database if one exists. 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).
+the issue tracking database if one exists. 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>
@@ -416,20 +438,22 @@
<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
+corresponding issue in the issue 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
+isolated the bug to a small test case and filed an issue in the issue
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
+(such as an optimization tweak), either create an enhancement request
+in the issue tracking database and attach the patch to it or, for
+small changes, 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:stdcxx-dev@incubator.apache.org">stdcxx-dev@incubator.apache.org</a>.
</p>
@@ -454,28 +478,63 @@
<div class="section">
<p>
+Every patch should address at most one issue from the issue tracking
+database. Separate issues should be addressed in separate patches.
+An issue that discusses more than one bug or one enhancement should
+either be first split up into multiple issues, or into multiple <a
+class="external"
+href="http://www.atlassian.com/software/jira/docs/latest/subtasks_creating.html">subtasks</a>,
+before submitting a patch for each.
+
+ </p>
+ <p>
+
+In order to make them easy to review and revert, if necessary (in case
+they cause regressions not dicovered during review), patches should be
+as small as possible. Changes should be limited to the bare minimum
+necessary to address the issue. Gratuitous edits such code
+reformatting or renanaming of variables should be avoided. Such
+changes should be made separately and independently of any functional
+changes to the code.
+
+ </p>
+ <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 reading the ChangeLog or looking
+Detailed description of the change. It should be obvious from reading
+the description alone (i.e., without reading the Change Log or looking
at the source code) what the change does and why. See <a
href="http://mail-archives.apache.org/mod_mbox/incubator-stdcxx-dev/200512.mbox/%3c43AC76EB.9010509@roguewave.com%3e">this
post</a> for an example of such a description.
</li>
<li>
+
+Changes that might have an impact on the efficiency of the changed
+component should be accompanied by a small program exercising the
+component, either by timings showing the performance difference
+between the original and the changed code in user and system times
+(for example, using the POSIX <a class="external"
+href="http://www.opengroup.org/onlinepubs/009695399/utilities/time.html"><code>time</code></a>
+command), or by sizes of the original and the code for changes
+affetcting the space efficiency of code.
+
+ </li>
+ <li>
<p>
-Change Log entry. The format of Change Log entries follows the
+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.
+advantage of the <code>add-change-log-entry</code> command. See the <a
+class="external"
+href="http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log.html#Change-Log">Change
+Log</a> section of the Emacs manual.
</p>
<p>
@@ -483,11 +542,12 @@
Each Change Log entry starts with a submission date followed by the
name and email address of the submitter, all on the same
line. Separated by a blank line is a reference to the <i>issue key</i>
-representing the corresponding issue in the bug tracking database (if
-applicable). The rest of the entry consists of a bullet list of
+representing the corresponding issue in the issue tracking database
+(if applicable). The rest of the entry consists of a bullet list of
changed files and the names and descriptions of the symbols affected
-by the change in each file. For examples of stdcxx Change Log entries
-view the logs of some stdcxx source files, such as <a
+by the change in each file. A maximum line length of 78 characters
+should be observed. For examples of stdcxx Change Log entries view the
+logs of some stdcxx source files, such as <a
href="http://svn.apache.org/viewcvs.cgi/incubator/stdcxx/trunk/src/time_put.cpp?rev=368527&view=log">time_put.cpp</a>,
or <a
href="http://svn.apache.org/viewcvs.cgi/incubator/stdcxx/trunk/src/wcodecvt.cpp?rev=369110&view=log">wcodecvt.cpp</a>.
@@ -496,10 +556,10 @@
<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
+the issue tracking database to be able to update the issue in the
+issue 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>
@@ -544,7 +604,7 @@
files. Multiple files can be submitted individually or as a gzipped
tarball. Be aware of the size limit imposed on posts to the mailing
list. In general, it is better to avoid posting very large files and
-instead attach them to an issue in the bug tracking database.
+instead attach them to an issue in the issue tracking database.
</p>
<p>