@@ -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 bug tracking -database. 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 and choose Bug for the Issue +Type. 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.

-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 @@

@@ -396,10 +417,11 @@ href="mailto:stdcxx-dev@incubator.apache.org">stdcxx-dev@incubator.apache.org. 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).

@@ -416,20 +438,22 @@

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.

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, stdcxx-dev@incubator.apache.org.

@@ -454,28 +478,63 @@

+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 subtasks, +before submitting a patch for each. + +

+ +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. + +

+ Every patch should include the following information:

-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 this post for an example of such a description.
+ +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 time +command), or by sizes of the original and the code for changes +affetcting the space efficiency of code. + +
-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. Emacs users can take -advantage of the add-change-log-entry -command. +advantage of the add-change-log-entry command. See the Change +Log section of the Emacs manual.

@@ -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 issue key -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 time_put.cpp, or wcodecvt.cpp. @@ -496,10 +556,10 @@
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 STDCXX-NNN where the NNN part is -the issue number (for example, STDCXX-NNN where the NNN part +is the issue number (for example, STDCXX-2).
@@ -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.

Reporting a Bug

Requesting an Enhancement

Submitting Patches