Leandro Lucarella wrote:
Hello, I just created a DIP (D Improvement Proposal) index[1] and the
first DIP (DIP1), a DIP template[2].
Here is the complete text, to make easier to discuss it:
------------------------------------------------------------------------------
= DIP1: DIP Template =
DIP: 1
Title: DIP Template
Version: 1
Status: Draft
Created: 2009-07-07
Last Modified: 2009-07-07
Author: Leandro Lucarella <[email protected]>
== Abstract =
This is a sample template to easily start a new DIP. DIPs can be fairly
informal for now, but at least the leading metadata should be included, and a
short abstract.
== Rationale =
Keeping track of improvement proposals is very hard and not well documented
organized. Having a template (and a process) for such proposals can improve the
situation significantly.
== Usage =
To start a new DIP you can go to Edit link and copy the source of this DIP,
then go to [DiPs DIP index] and add a new item in the list. The DIP number
should be one more than the last DIP in the index (for example, if the DIP1 is
the last DIP, your DIP should be DIP2). The link in the index should have the
form: "[DiPx DIPx (title)]: resume", where 'x' is the DIP number, 'title' is
the DIP title and 'resume' is a short description about the DIP.
Save the DIP index page and click on the '?' at the side of the new link. Now
you are editing the new DIP you just created, now paste the copied *'source*
text from this template and replace all the you need.
Remember to update the metadata at the start of the DIP, and keep it as a Draft
at the beginning. When your DIP is done, you should announce it in the News
Group for discussion, with a subject like this: '''new DIPx: title''' (where
one more time ''x'' is the DIP number and ''title'' is the DIP title).
You should always put you DIPs in the Public Domain (or a similarly permissive
license but use Public Domain unless you're very sure of what you're doing).
== Copyright =
This document has been placed in the Public Domain.
------------------------------------------------------------------------------
[1] http://www.prowiki.org/wiki4d/wiki.cgi?DiPs
[2] http://www.prowiki.org/wiki4d/wiki.cgi?DiP1
I think this is a good idea. :) Regarding the template, I think there
should be one more section, called "Description". Then each DIP would be
organised as follows:
Abstract:
Short summary of description, rationale and usage.
Description:
Detailed description of proposal.
Rationale:
Explanation of why proposal has been made, why the new feature
should be included.
Usage:
Examples, etc.
Also, each DIP should have a "Status/comments" section at the bottom
where Walter & co. can say whether the proposal needs more
specification, better description, etc.
-Lars
