stdcxx-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From se...@apache.org
Subject svn commit: r560651 - /incubator/stdcxx/site/bugs.html
Date Sun, 29 Jul 2007 00:31:24 GMT
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  <sebor@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>



Mime
View raw message