Difference between revisions of "DIP1"
m (→Description) |
(Change last modified date to auto-updating.) |
||
| (7 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | {| class="wikitable" | |
| − | + | !Title: | |
| − | + | !'''DIP Template''' | |
| − | + | |- | |
| − | + | |DIP: | |
| − | |||
| − | |||
| − | |||
| − | |DIP: | ||
|1 | |1 | ||
| − | | | + | |- |
| − | |||
| − | |||
| − | |||
|Version: | |Version: | ||
|3 | |3 | ||
| − | | | + | |- |
|Status: | |Status: | ||
|Draft | |Draft | ||
| − | | | + | |- |
|Created: | |Created: | ||
|2009-07-07 | |2009-07-07 | ||
| − | | | + | |- |
|Last Modified: | |Last Modified: | ||
| − | | | + | |{{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY}} |
| − | | | + | |- |
|Author: | |Author: | ||
|Leandro Lucarella | |Leandro Lucarella | ||
| − | | | + | |- |
|Links: | |Links: | ||
| − | | | + | |[[DIP1/Archive]] — [http://www.digitalmars.com/d/archives/digitalmars/D/announce/dmd_1.046_and_2.031_releases_16320.html#N16448 NG discussion that triggered the DIP] |
| − | [[DIP1/Archive]] | ||
— [http://www.digitalmars.com/d/archives/digitalmars/D/new_DIP1_DIP_Template_92908.html NG announcement and discussion] | — [http://www.digitalmars.com/d/archives/digitalmars/D/new_DIP1_DIP_Template_92908.html NG announcement and discussion] | ||
|} | |} | ||
| − | |||
| − | |||
== Abstract == | == 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. | 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 == | == 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. | 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. | ||
| − | |||
| − | |||
== Description == | == Description == | ||
| − | |||
| − | |||
| − | |||
A DIP is a D Improvement Proposal, a way propose changes to the language in a sightly more formal way than just throwing out the idea in the news group. A DIP should have an structure similar to this one, but nothing is set in stone, you can add or remove sections and/or metadata as long as the DIP is both clean and complete, but try to stick to this template as a bare minimum unless is really necessary to remove something. | A DIP is a D Improvement Proposal, a way propose changes to the language in a sightly more formal way than just throwing out the idea in the news group. A DIP should have an structure similar to this one, but nothing is set in stone, you can add or remove sections and/or metadata as long as the DIP is both clean and complete, but try to stick to this template as a bare minimum unless is really necessary to remove something. | ||
| Line 59: | Line 38: | ||
== Usage == | == 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: <nowiki>[[DIPx]]</nowiki>, Title, Status, resume. Where x is the DIP number, title is the DIP title and resume is a short description about the DIP. | 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: <nowiki>[[DIPx]]</nowiki>, Title, Status, resume. Where x is the DIP number, title is the DIP title and resume is a short description about the DIP. | ||
| Line 71: | Line 47: | ||
== Recommendations == | == Recommendations == | ||
| − | |||
| − | |||
When writing a DIP, try not to express your opinion. DIPs should provide facts and be as objective as possible. Even when that's pretty hard, you can make the DIP look more objective by not using, for example, "I prefer XXX because YYY". If YYY is an objective advantage, write that in a more objective way, like "XXX can be a better option because YYY". Try to leave non-technical personal preferences aside; "XXX can be a better option because the syntax is nicer" is not good enough even when you don't say "I prefer". | When writing a DIP, try not to express your opinion. DIPs should provide facts and be as objective as possible. Even when that's pretty hard, you can make the DIP look more objective by not using, for example, "I prefer XXX because YYY". If YYY is an objective advantage, write that in a more objective way, like "XXX can be a better option because YYY". Try to leave non-technical personal preferences aside; "XXX can be a better option because the syntax is nicer" is not good enough even when you don't say "I prefer". | ||
Try not to include half-baked ideas. If you are not sure about something, leave it outside the DIP and write it on the NG announcement instead for further discussion. The idea can be added to the DIP in the future when it is in a better shape. | Try not to include half-baked ideas. If you are not sure about something, leave it outside the DIP and write it on the NG announcement instead for further discussion. The idea can be added to the DIP in the future when it is in a better shape. | ||
| − | |||
| − | |||
== Abstract == | == Abstract == | ||
| − | |||
| − | |||
Make the abstract as descriptive as possible (while keeping it brief). From an abstract you should be able to tell what the DIP is about, you should introduce for every non-trivial concept a person should know for understanding the DIP (or provide links if you can't briefly describe those concepts in the abstract). Don't copy the title of the DIP to use it as an abstract. Ideally an abstract should be a paragraph 5 to 10 lines long. | Make the abstract as descriptive as possible (while keeping it brief). From an abstract you should be able to tell what the DIP is about, you should introduce for every non-trivial concept a person should know for understanding the DIP (or provide links if you can't briefly describe those concepts in the abstract). Don't copy the title of the DIP to use it as an abstract. Ideally an abstract should be a paragraph 5 to 10 lines long. | ||
| − | |||
| − | |||
== Rationale == | == Rationale == | ||
| − | |||
| − | |||
Rationale should be complete. When the DIP tries to solve a problem, try to describe that problem as detailed as possible. If you have links to the NG describing the problem more deeply, used them. All the background information is welcome. | Rationale should be complete. When the DIP tries to solve a problem, try to describe that problem as detailed as possible. If you have links to the NG describing the problem more deeply, used them. All the background information is welcome. | ||
| − | |||
| − | |||
== NG Announcement == | == NG Announcement == | ||
| − | |||
| − | |||
When posting the DIP announcement to the NG, please copy the abstract, so people can easily know what is it about and follow the link if they are interested. | When posting the DIP announcement to the NG, please copy the abstract, so people can easily know what is it about and follow the link if they are interested. | ||
| − | |||
== Copyright == | == Copyright == | ||
| − | |||
This document has been placed in the Public Domain. | This document has been placed in the Public Domain. | ||
[[Category: DIP]] | [[Category: DIP]] | ||
Latest revision as of 01:53, 17 January 2015
| Title: | DIP Template |
|---|---|
| DIP: | 1 |
| Version: | 3 |
| Status: | Draft |
| Created: | 2009-07-07 |
| Last Modified: | 2015-01-17 |
| Author: | Leandro Lucarella |
| Links: | DIP1/Archive — NG discussion that triggered the DIP |
Contents
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.
Description
A DIP is a D Improvement Proposal, a way propose changes to the language in a sightly more formal way than just throwing out the idea in the news group. A DIP should have an structure similar to this one, but nothing is set in stone, you can add or remove sections and/or metadata as long as the DIP is both clean and complete, but try to stick to this template as a bare minimum unless is really necessary to remove something.
A DIP should represent a problem the community wants to resolve and not just a specific resolution to a problem. This allows the DIP to be a central hub for any given problem. If a resolution is radically different from the current state of the DIP, an alternative DIP could be created as a sub page, e.g. under /DIP1/Alternatives/Alt1. The DIP should be created in its entirety such that it could replace the current DIP through simple copy and past.
Usage
To start a new DIP you can go to Edit link and copy the source of this DIP, then go to 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]], Title, Status, 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 new red 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).
Recommendations
When writing a DIP, try not to express your opinion. DIPs should provide facts and be as objective as possible. Even when that's pretty hard, you can make the DIP look more objective by not using, for example, "I prefer XXX because YYY". If YYY is an objective advantage, write that in a more objective way, like "XXX can be a better option because YYY". Try to leave non-technical personal preferences aside; "XXX can be a better option because the syntax is nicer" is not good enough even when you don't say "I prefer".
Try not to include half-baked ideas. If you are not sure about something, leave it outside the DIP and write it on the NG announcement instead for further discussion. The idea can be added to the DIP in the future when it is in a better shape.
Abstract
Make the abstract as descriptive as possible (while keeping it brief). From an abstract you should be able to tell what the DIP is about, you should introduce for every non-trivial concept a person should know for understanding the DIP (or provide links if you can't briefly describe those concepts in the abstract). Don't copy the title of the DIP to use it as an abstract. Ideally an abstract should be a paragraph 5 to 10 lines long.
Rationale
Rationale should be complete. When the DIP tries to solve a problem, try to describe that problem as detailed as possible. If you have links to the NG describing the problem more deeply, used them. All the background information is welcome.
NG Announcement
When posting the DIP announcement to the NG, please copy the abstract, so people can easily know what is it about and follow the link if they are interested.
Copyright
This document has been placed in the Public Domain.
