Bugs in Apache C++ Standard Library

Wikipedia, the free online encyclopedia, defines a bug as follows:

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.

1. 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 issue tracking database 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 Reporting a Bug 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).

2. 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 reference 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 user@stdcxx.apache.org and ask. If the problem is indeed a bug, go back to step 1.

3. 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 C++ Standard from the ANSI eStandards store. If your request is not in conflict with any requirements of the C++ standard, open a request for Improvement or New Feature to the issue tracking database (see the stdcxx issue tracking database documentation for the available issue types).

The table below contains links to a number of saved bug tracking database queries along with their summary results. The version column indicates the version and contains a link to a query that pulls up all issues of any type scheduled to be fixed in that version. The Resolved column indicates the number of issues of any type resolved (but not closed) in that version. The Closed column indicates the number of issues of any type closed in that version. The Bugs column indicates the number of issues of type Bug resolved or closed in that version. The Improvements column indicates the number of issues of type Improvement resolved or closed in that version. The New Features column indicates the number of issues of type New Feature resolved or closed in that version. The Regressions column indicates the number of issues of any type both introduced and resolved or closed in that version. The Pending column indicates the number of issues of any type schedule for that version that haven't yet been resolved or closed.

The value in each cell in the table is either a number (for released versions), or TBD (for To Be Determined) for versions that are in active development, or N/A (for Not Available) for a future version for which there is no data yet.

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 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 hardware architectures.

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 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 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, 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 assert() macro to assert any postconditions. Refer to existing bug reports (such as STDCXX-2) for examples. By following this advice you will increase the chances that the bug will be resolved quickly.

The process for requesting enhancements and new features in stdcxx is essentially the same as the process for Reporting a bug except that instead choosing Bug as the Issue Type you will choose either Improvevement when requesting an enhancement to an existing feature, or New Feature when requesting an entire new feature.

Committers who follow the Review-Then-Commit policy, and non-committer Contributors without commit (write) access to the stdcxx source repository must submit patches for review and approval before they can be committed by someone with commit access. If you would like to submit a patch for a bug that you or someone else reported, you can do so in two ways:

1. Post the patch to the project development mailing list, dev@stdcxx.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 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).
2. 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. This approach is preferable to sending the patch to the mailing list when the patch is large or when the patch sent to the project development mailing list gets mangled or stripped by the list management software.

If you would like to submit a patch for a bug that doesn't have a 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 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), 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, dev@stdcxx.apache.org.

Patches for documentation or project web pages should follow the same process as above, except that a test case isn't necessary in most situations. A possible exception is a patch for code example listed in the Class Reference.

In all cases, make sure your patch follows the expected Patch Format described below.

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:

1. 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.
2. 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.

3. 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. See the Change Log section of the Emacs manual. VIM users can install the ft-changelog-plugin and use the NewChangelogEntry command to get help with the formatting.

   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 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. 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 time_put.cpp, or wcodecvt.cpp.

   The format of the issue key is especially important in order for the 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 STDCXX-NNN where the NNN part is the issue number (for example, STDCXX-2).

4. 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 patch utility, or in the Unified format produced by the Subversion svn diff command by default as well as by the GNU diff utility and understood by GNU patch. When creating patches on Windows it is important to keep in mind that the newline sequences (carriage-return followed by line-feed, or <CR><LF>) may not be recognized by traditional UNIX implementations of the patch utility (as is the case on Solaris). For portability, it is best to strip the carriage-returns from the patch before posting it. The standard tr utility can be used to do that.

New Files