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 <llucax@gmail.com>

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

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Dentro de 30 años Argentina va a ser un gran supermercado con 15
changuitos, porque esa va a ser la cantidad de gente que va a poder
comprar algo.
	-- Sidharta Wiki

FYI, you could have a DIP as a subpage to DiPs, which in turn could be a subpage to LanguageDevelopment. Personally I'd suggest a Proposal subpage cantaining the DIPS, which in turn hold any pages they need.

http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/Proposal http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/Proposal/DIP1 http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/Proposal/DIP1/ DiscussionArchive

I didn't create the pages, just examples if you want to move it. The internal structure isn't as important as the visual structure (how you get there), but I think they somewhat go hand and hand.

----

As for the DIP template, I like the idea. It lays out a very clear objective as to what should go into a proposal. In fact, when I get around to it I'll probably use it to create DIPs that have already been turned down.

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 <llucax@gmail.com>
> 
> == 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

Hi not a bad idea. Is a prowiki suitable enough as opposed to any other content management systems.

Some inspiration:

http://www.python.org/dev/peps/pep-0000/
http://www.tcl.tk/cgi-bin/tct/tip
http://www.erlang.org/eeps/
http://wiki.php.net/rfc

Lars T. Kyllingstad Wrote:

> Leandro Lucarella wrote:
> > 
> > [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.

I agree, but think the description section should come after usage. That should be a more natural reading order...

Also, I think we should list the available values for status, and possibly add sections to the DIP as it gets more mature. Off the top of my head:

Draft
• Description section optional

Stable Design
• Detailed description required. Major design changes should become a new draft DIP.
• Reaction from Walter & Co. optional

Rejected
• Reaction from Walter & Co. required. Shouldlist specific faults

Soliciting Patches
• Implementation thought
• Submitted patches (with quality remarks about each patch)

Accepted
• Links - changeset, final docs on digitalmars.com, etc...

Jesse Phillips, el  8 de julio a las 02:04 me escribiste:
> FYI, you could have a DIP as a subpage to DiPs, which in turn could be a subpage to LanguageDevelopment. Personally I'd suggest a Proposal subpage cantaining the DIPS, which in turn hold any pages they need.
> 
> http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/Proposal http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/Proposal/DIP1 http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/Proposal/DIP1/ DiscussionArchive

That's a good suggestion! I like it. If nobody complains about it I will use the new structure.

BTW, I used "DiP1" as wiki page because DIP1 wasn't recognized as a wiki page. Do you know if it's possible to use DIP1?

I'd like to use this structure:
LanguageDevel/DIPs/ (index)
LanguageDevel/DIPs/DIP1 (current version)
LanguageDevel/DIPs/DIP1/Archive (previous versions)
LanguageDevel/DIPs/DIP1/Archive/Revision1 (previous versions)
LanguageDevel/DIPs/DIP1/Archive/Revision2 (previous versions)
LanguageDevel/DIPs/DIP1/DiscussionLinks (links to discussions)

Maybe it's a little bloated for now...

> I didn't create the pages, just examples if you want to move it. The internal structure isn't as important as the visual structure (how you get there), but I think they somewhat go hand and hand.

BTW, can pages be moved or should I copy the contents to a new page and then remove the old one?

> ----
> 
> As for the DIP template, I like the idea. It lays out a very clear objective as to what should go into a proposal. In fact, when I get around to it I'll probably use it to create DIPs that have already been turned down.

That would be nice. DIPs that are turned down should be kept as rejected so people don't come over and over again suggesting the same thing. Having the discussion about why it was turned down would be extremelly useful.

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Hey you, out there on your own
Sitting naked by the phone
Would you touch me?

Lars T. Kyllingstad, el  8 de julio a las 11:44 me escribiste:
> 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.

Yes, it's unclear from the text in the current DIP but the idea is that a DIP can have as many sections are needed, but Description probably will be in every DIP so it will be a good idea to add it.

I'll add the Description section and clarify that DIP can add new sections as needed.

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

I think this can be in the NG discussion. There is already a "Status" field/metadata. The possible statuses are not defined yet but I think that we can use PEP statuses: http://www.python.org/dev/peps/pep-0001/#pep-work-flow

We can add an "Incomplete state" maybe, but I think a DIP in the Draft status is implicitly incomplete.

I will link this discussion to the DIP1 =)

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
JUNTAN FIRMAS Y HUELLAS POR EL CACHORRO CONDENADO A MUERTE...
	-- Crónica TV

Jason House, el  8 de julio a las 08:50 me escribiste:
> Lars T. Kyllingstad Wrote:
> 
> > Leandro Lucarella wrote:
> > > 
> > > [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.
> 
> I agree, but think the description section should come after usage. That should be a more natural reading order...

About the order, I prefer the description first but I can live with the usage first. But I think the rationale should be just after the abstract. I think the order should be:

Abstract:
     Short summary of description, rationale and usage.
Rationale:
     Explanation of why proposal has been made, why the new feature
     should be included.
Description:
     Detailed description of proposal.
Usage:
     Examples, etc.
Other:
     Other sections as needed.

I don't even think the Usage will always be there (there could be DIPs for removing a feature for example).

> Also, I think we should list the available values for status, and possibly add sections to the DIP as it gets more mature. Off the top of my head:
> 
> Draft
> ? Description section optional
> 
> Stable Design
> ? Detailed description required. Major design changes should become a new draft DIP.
> ? Reaction from Walter & Co. optional
> 
> Rejected
> ? Reaction from Walter & Co. required. Shouldlist specific faults
> 
> Soliciting Patches
> ? Implementation thought
> ? Submitted patches (with quality remarks about each patch)
> 
> Accepted
> ? Links - changeset, final docs on digitalmars.com, etc...

I was thinking about the PEP statuses (to be honest I was inspired by PEPs when doing this, I hope this doesn't make Python haters resistant to the proposal now ;). But being a different language there could be different needs so we can pick a new set of statuses of our own. I didn't wanted to specify all these details for now to avoid bloat.

I think we should start with easy to write, not *too* formal proposals, and increment the level of detail in the future, as the need comes more evident, so we don't get too bureaucratic without reason.

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
La máquina de la moneda, mirá como te queda!
	-- Sidharta Kiwi

Tim Matthews, el  8 de julio a las 22:41 me escribiste:
> Hi not a bad idea. Is a prowiki suitable enough as opposed to any other content management systems.

I started with the current Wiki because is what we have now. I really don't like the current Wiki syntax, but I didn't wanted to add obstacles to this idea because I think D is needing some kind of "standard" proposal mechanism.

There is plenty of time in the future to change to another way to write/maintain DIPs when needed.

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
No debemos temer a la muerte, porque es la mejor recompensa de la vida.
	-- Ren & Stimpy

Leandro Lucarella Wrote:

> Jason House, el  8 de julio a las 08:50 me escribiste:
> > Lars T. Kyllingstad Wrote:
> > 
> > > Leandro Lucarella wrote:
> > > > 
> > > > [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.
> > 
> > I agree, but think the description section should come after usage. That should be a more natural reading order...
> 
> About the order, I prefer the description first but I can live with the usage first. But I think the rationale should be just after the abstract. I think the order should be:
> 

<snip/>

I hope we can avoid format wars -- surely we're flexible enough to evaluate DIPs without insisting on a particular order of presentation. Different proposals may benefit from different presentations. The template is a great starting point.

(I know the posters in this thread aren't insisting on a particular order, just tossing out ideas.)

I think one of the strengths of creating DIPs is to keep track of proposals -- both to keep us from re-inventing the wheel and to keep good ideas from getting lost in the NG. Some ideas that seem trivial generate a lot of posts and occasionally descend into flame wars, while other, meatier proposals languish just because no one responds.

I would suggest that the proposer also include, if applicable, which language version (or which component or library, etc.) their proposal would affect, and whether it is a breaking change.

The Java Community Process (which is very formal and glacially slow) uses a question based format that may be helpful here too. (I mean the list of questions -- not that we should use questions.)  One of their questions is "Why isn't this need met by existing specifications?". Proposers might consider this -- it could separate the bicycle shed ideas from more fundamental ones.

Paul