The DIP Authoring Process
DIP submission is open to anyone aiming to improve the D programming language and possessing the motivation to see a proposal through to implementation. Before an author submits a DIP, it is important to understand the goals of the DIP process, which can be time consuming and is not guaranteed to have a positive outcome for the DIP author(s).
The language maintainers have high standards for DIP quality. All DIP authors should read the DIP Guidelines before embarking on the process. Once submitted, a DIP will undergo a series of community reviews with the aim of uncovering technical issues and improving the overall quality of the DIP. This process is not one of community approval, but one of collaborative improvement. By the time the DIP reaches the last stage of the process, review by the language maintainers, it is hoped the preceding stages will have produced a stronger proposal (though that by no means guarantees approval).
This document describes the responsibilities of DIP authors at each stage the DIP process.
When to Write a DIP
The following are categories of changes that warrant a DIP:
- changes to the language itself, such as syntax/semantics
- changes to the functional behavior of code generated by the compiler
Be sure to consider the full impact of any change when deciding if it warrants a DIP. Even seemingly innocuous changes can have an impact that is not immediately obvious. Anyone considering a serious proposal who isn't sure if a DIP will be required can make an exploratory post in the D General discussion forum, but the rule of thumb should be, "When in doubt, write a DIP."
Step 1 - Determine the Point of Contact
Once the determination is made that a DIP is required, an individual must be selected to serve as the Point of Contact (POC). Every DIP submitted to the DIP Repository must be assigned a POC. If the DIP has a single author, the author is required to be the POC. If there are multiple authors, they must select one from among themselves to act as the POC before the DIP is submitted.
The POC is responsible for communicating with the DIP manager or language maintainers as required from the time the DIP is submitted until the time it receives its final disposition or, if accepted, until the implementation has been completed, e.g. merged into the appropriate repository. The POC is not required to be the owner of the GitHub account from which the DIP is submitted.
If communication with the POC is lost, then at least 30 days after the last known contact, the DIP manager may attempt to find a new POC. If, after 60 days, no one has taken over the role, the DIP manager will consult with the language maintainers to determine the disposition of the DIP. The DIP may be accepted as is, rejected, postponed, or marked as
Abandoned at their discretion. Abandoned DIPs may be resurrected by anyone at any time.
It is the responsibility of the DIP manager to provide the POC with regular updates throughout the process. If the POC receives no updates from the DIP manager after 30 days, and the DIP manager fails to respond to requests, the POC may contact the language maintainers directly to determine how to proceed.
Step 2 - Fork the DIP Repository
The primary DIP author will fork the DIP repository and copy the
Template.md file to the
DIPs subdirectory using the following naming convention:
1NNN-(POC initials).md, where
(POC initials) is replaced with the initials of the POC, e.g.
1NNN-JQC.md when the POC is Joe Q. Coder.
Step 3 - The Development Stage
This is where the first draft of the DIP is assembled by the DIP author(s). The DIP author(s) should adhere to the structure of the [DIP Template] and should not change the ordering of the headings. New subheadings may be added as needed. The DIP author is expected to complete sections marked as "Required".
Generally, it will be the primary DIP author who forks the DIP Repository. The new DIP must follow the naming convention presented in Step 2 above, i.e.
1NNN-(POC initials).md. The DIP author should not submit a pull request to the DIP Repository until the first draft is complete. The DIP Repository is not the place for the initial development of a DIP. The DIP author(s) should develop the first draft of the DIP in the newly forked repository. A completed first draft is one that, if it were perfect and required no further revision, would be ready to proceed through the entirety of the DIP process.
If community feedback is desired during the Development Stage, the DIP author(s) should announce in the D Forums that the DIP is in development and ask for feedback, providing a link to the DIP in the forked repository. Any pull request submitted to the DIP Repository before the DIP is in a first draft state will be rejected.
Step 4 - Draft Review
When the first draft of the DIP is ready and the POC is prepared to begin the Draft Review, the primary DIP author should submit the DIP to the DIP Repository in the form of a pull request. The DIP should maintain the same naming convention. At no point should anyone other than the DIP manager assign a number to the DIP. The merging of the pull request by the DIP manager signifies the end of the Development Stage and the beginning of the Draft Review. The DIP manager should acknowledge the DIP within two weeks of its submission by ensuring the status of the DIP is set to
Draft and/or leaving a comment in the pull request thread. At some point during the Draft Review period, the DIP manager may post an announcement in the D Forums requesting feedback.
While the DIP is in Draft Review, DIP authors are expected to acknowledge all unique feedback on the DIP with a reply and are are asked to seriously consider if any given feedback warrants revision of the DIP. They are free to revise the DIP as much or as little as they deem necessary. To emphasize, DIP authors are not required to revise based on every bit of feedback, but are expected to consider the value of all feedback in good faith. If the DIP authors disagree with any feedback, they should say as much in a reply.
The DIP manager will contact the POC of a DIP when the time comes to promote one from Draft Review to determine if the POC is ready to move forward. If so, the DIP manager will initiate an editing process to tighten up the language of the DIP. The POC will be informed of which edit suggestions are mandatory and which are optional. Failure to accept mandatory edits will prohibit the DIP from moving forward. In rare cases, the DIP manager may request revision of the content and, rarer still, may determine that such revisions are mandatory. Such cases should not be necessary if the Draft Review works as intended.
The Review Process document describes the purpose and procedure of the Draft Review.
Step 5 - Community Review
When a DIP is in Community Review, the DIP manager will not accept any pull requests for the DIP. DIP authors should refrain from making any changes to the DIP during the review in order to minimize the odds of annoying merge conflicts later. When the review has completed, the DIP manager will update the DIP with its new status and a summary of the review. At this point, the DIP author is free to submit a pull request containing any revisions arising from the review. If the revisions are significant, the DIP manager may require another round of Community Review.
The Review Process document describes the purpose and procedure of the Draft Review.
Step 6 - Final Review
As above, the DIP manager will accept no pull requests and DIP authors are discourage from making any edits while a DIP is in Final Review. Ideally, the DIP will require no revision after the Final Review is complete. If revision is required, it should be minor. After the DIP manager has updated the DIP with its new state and a review summary, the POC will be notified if the DIP manager requires any revisions. The DIP manager will also give the DIP author(s) time to make any other minor revisions deemed necessary.
Step 7 - Formal Assessment
Ideally, a DIP under review by the language maintainers would require no further revision. Such a DIP is rare. The language maintainers often require minor revision of a DIP, frequently to improve the language, add clarification, adjust certain parameters, etc. The DIP manager will notify the POC which revisions are mandatory and which are optional. DIP authors should be prepared to respond to revision requests as soon as possible and should understand that failure to apply mandatory revisions could lead to rejection of the DIP or cause a decision to be postponed.