|Project:||Programming Language C++, Library Working Group|
|Reply-to:||Alisdair Meredith <firstname.lastname@example.org>|
Revised document: ISO terminology has changed and this
document has been updated accordingly.
Increasing the chance of acceptance
Guidelines for a proposal document
Organization of a typical proposal
The C++ standards committee is soliciting proposals for additional library components. Such proposals can range from small (addition of a single signature to an existing library) to large (something bigger than any current standard library component).
In a change from past practice, the committee is processing multiple library work items in parallel, and any resulting domain specific technical specifications will ship when ready rather than waiting for completion of single large technical specification.
This call for proposals in open ended; there is no cutoff date. As a practical matter, the committee is early in the post-C++11 revision cycle, and so the next year is a particularly good window of opportunity for library proposals.
The committee welcomes proposals with or without formal standard wording (often known as "standardese"). This is a change from past practice, and is intended to encourage library developers to step forward with proposals.
The committee evaluates each proposal on its own merits. Here are some suggestions to increase the chance of acceptance.
The committee prefers proposals based on existing practice. Existing practice is not an absolute rule, but it is an important guideline that the committee use to judge the value of a proposal. A proposal must be implementable, and the best evidence that something is implementable is that it has been implemented. A proposal based on existing practice gives the committee more confidence that the proposal solves a real problem and that its interface has evolved to serve the needs of real users.
The preference for existing practice does not necessarily mean that a proposal has to be exactly the same as some existing library. A proposal might adjust an existing library's interface to match the style of the C++ standard library, or a proposal might attempt to reconcile the interfaces of several preexisting libraries, or a proposal might be based on existing practice in some other language.
The committee does occasionally adopt a completely experimental library, even without widespread existing practice. Such proposals are usually small enough and simple enough that there is low risk that widespread usage will turn up serious additional problems. And even these really simple proposals need to have been implemented.
A proposal is more than a wish. "C++ should support JPEG manipulation" is not a proposal. A class synopsis is not a proposal. Even the documentation for a widely used library is not a proposal.
A proposal must provide the C++ committee with the information it needs to determine if the proposed library component is suitable for standardization. The most straightforward way to do this is to answer the questions asked in the Organization of a typical proposal section below.
These things are important so that the standardization committee can evaluate the proposal. A clear overall proposal is more important than finalizing the exact standardese wording. You should expect a proposal to go through at least one revision before it is accepted, so if the committee likes a proposal, there will be a later opportunity to adjust the precise wording based on feedback from the committee.
Assume that the target for your proposal is a library technical specification, unless it modifies an existing standard library component or header. In that case, assume your proposal is targeted at the standard itself. The Library Working Group's procedure is now to wait until technical work is complete before making a final decision on which route will be taken to publication, but the clear preference is for new library components to go into TRs, while modifications go into the standard.
This is a template for a typical proposal for a medium to high complexity feature. Proposals for simpler features will go into less detail.
In addition to the section headings given in the template, feel free to use the questions as sub-headings. Italicized text should be replaced by the indicated content.
Document number: Nnnnn=yy-nnnn Date: yyyy-mm-dd Project: Programming Language C++, Library Working Group Reply-to: Your name and email address; list multiple authors if applicable. It is OK to obfuscate the address like this: "Jane Proposer <jane at somewhere dot com>
I. Table of Contents
A very brief high level view of your proposal, understandable by C++ committee members who are not necessarily experts in whatever domain you are addressing.
III. Motivation and Scope
Why is this important? What kinds of problems does it address? What is the intended user community? What level of programmers (novice, experienced, expert) is it intended to support? What existing practice is it based on? How widespread is its use? How long has it been in use? Is there a reference implementation and test suite available for inspection?
IV. Impact On the Standard
What other library components does does it depend on, and what depends on it? Is it a pure extension, or does it require changes to standard components? Can it be implemented using C++11 compilers and libraries, or does it require language or library features that are not part of C++11?
V. Design Decisions
Why did you choose the specific design that you did? What alternatives did you consider, and what are the tradeoffs? What are the consequences of your choice, for users and implementers? What decisions are left up to implementers? If there are any similar libraries in use, how do their design decisions compare to yours?
VI. Technical Specifications
The committee needs technical specifications to be able to fully evaluate your proposal. Eventually these technical specifications will have to be in the form of full text for the standard or technical specification, often known as "Standardese", but for an initial proposal there are several possibilities:
- Provide some limited technical documentation. This might be OK for a very simple proposal such as a single function, but for anything beyond that the committee will likely ask for more detail.
- Provide technical documentation that is complete enough to fully evaluate your proposal. This documentation can be in the proposal itself or you can provide a link to documentation available on the web. If the committee likes your proposal, they will ask for a revised proposal with formal standardese wording. The committee recognizes that writing the formal ISO specification for a library component can be daunting and will make additional information and help available to get you started.
- Provide full "Standardese." A standard is a contract between implementers and users, to make it possible for users to write portable code with specified semantics. It says what implementers are permitted to do, what they are required to do, and what users can and can't count on. The "standardese" should match the general style of exposition of the standard, and the specific rules set out in 17.5, Method of description (Informative) [description], but it does not have to match the exact margins or fonts or section numbering; those things will all be changed anyway.
Successful proposals for TR1 can be used as models. Examples include:
Please note that details of these procedures are likely to change. Please check the Library Working Group web site for the latest update to submission procedures.
The proposal may be in PDF, HTML, or plain text formats. To submit a proposal:
Add the document number to the document, and email it as an attachment to email@example.com. You will get a reply in a few days acknowledging receipt.
The proposal document will then appear in the next official committee mailing. The term "mailing" dates from when documents were circulated by physical mail. Mailings are published roughly three weeks before and two weeks after committee meetings, with mid-term mailings half way between meetings added to the schedule when needed. Remember to allow a couple of weeks before the meeting to request a document number, otherwise your proposal may not go out until the following mailing, especially if this will be your first submission.
The proposal is then presented to the LWG at the next C++ committee meeting (see www.open-std.org/jtc1/sc22/wg21/docs/meetings for meeting schedules). You should plan to attend and present your proposal yourself , or ensure that someone who understands your proposal can present it for you. Getting a proposal accepted is an interactive process, and it is almost certain that the committee will have questions. At the least, you need to be willing to respond to email queries.
This document is based on N1810, Library Extension TR2 Call for Proposals, by Howard Hinnant, Beman Dawes, and Matt Austern.