List of Stages
Although the specific needs of each Working Group (WG) and Task Force (TF) may vary, the following table describes the recommended stages in the development of a ToIP deliverable (e.g., a specification, guide, template, or white paper):
| # | Stage | Activity | Exit Criteria |
|---|---|---|---|
| 1 | Initiation | Introduce members; agree on vision, mission, scope, process, tools, and schedule | Consensus on vision, mission, scope, process, tools, and schedule |
| 2 | Problem Definition | Stakeholders propose use cases to build a map of what problems they need to solve for whom | Consensus on the problem map |
| 3 | Requirements | Extract and enumerate specific requirements from the problem map | Consensus on requirements |
| 4 | Design Principles | Develop the principles that should guide/govern design of the solution | Consensus on design principles |
| 5 | Proposals | Members submit proposed solution designs | No further proposals |
| 6 | Consolidation | Members identify common elements and seek to develop a consolidated proposal | Consensus on contents of first Working Draft |
| 7 | Working Drafts † | A cycle of publishing Working Drafts, raising and resolving issues, and agreeing on revisions | Consensus on first Public Review Draft |
| 8 | Implementers Drafts | OPTIONAL for technical specifications where implementation feedback is desired prior to finalization. | Sufficient implementation feedback received |
| 9 | Public Review Drafts | Same as Working Draft stage except with public review | Consensus (or vote) on WG Approved Draft |
| 10 | WG Approved Draft † | WG decision to submit for SC approval | Consensus (or vote) to submit for SC approval |
| 11 | ToIP Approved Draft † | SC decision to approve as ToIP Deliverable | Consensus (or vote) to approve |
† Stages officially recognized in the Linux Foundation Joint Development Foundation process.
Stages 1 thru 6 (Prior to Working Drafts)
It is understandable that many WGs or TFs (collectively, "groups") may want to get "right to work", i.e., pick up the pen and start drafting. Some may even get started via a contributed document or specification. However we strongly recommend that the group still take the time to deliberately go through stages 1 through 6 in order to make sure all group members are aligned and working from the same conclusions about the mission, scope, problem definition, and requirements. It is also highly recommended that all group members have the opportunity to present their own proposed solutions. This is the best way to build towards consensus in the Consolidation stage prior to formally commencing Working Drafts.
Stage 7: Working Drafts
When the group is ready to begin drafting, it must decide which collaboration tools it will use. ToIP offers two choices:
- Google Docs. This option is recommended if the group wants to minimize barriers for contributors. It can work well for non-technical deliverables, where intellectual property rights (IPR) for contributions are usually not an issue. In addition, Google docs is a low-friction tool for the early stages of drafting technical specifications—though it is still important to keep a clear record of which ToIP members make which contributions.
- GitHub Markdown documents. This option MUST be used for the final form of all ToIP technical specifications. It is also recommended for all other ToIP deliverables whenever possible because It has the advantage of keeping a strict, verifiable datestamped record of all contributions by author. It is also recommended as the final form for any ToIP deliverable that wishes to take advantage of our Terminology Engine tools (produced by our Concepts and Terminology WG) for automatic linking and annotation of glossary terms.
<TODO: description or pointer to another wiki pages which explains which templates to use for Google docs/MS Word and GitHub and how to set them up>
Stage 8: Implementers Drafts (Optional)
If a deliverable is a technical specification, it is recommended to follow the IETF dictum of "rough consensus and running code", i.e., to provide evidence of completeness by demonstrating multiple interoperable implementations. The best way to do this is to publish at least one Implementers Draft that developers can use follow and provide feedback on. Depending on the complexity of the spec, more than one version of the Implementers Draft may be published, and the cycle will typically last at least few months, or even a year or more.
Note that explicitly calling a specification an Implementers Draft sends a clear signal that the spec is ready for implementation feedback—and that the group values that feedback before the spec goes final.
Stage 9: Public Review Drafts
If a deliverable is not a technical specification—or if the group feels it has received sufficient implementation feedback—he group MUST hold a public review of at least 15 days (30 to 60 days is RECOMMENDED) before the deliverable can be submitted for Working Group approval. During this public review period:
- The deliverable MUST be posted to GitHub (even if it is a PDF of a Google doc or Word doc).
- The public review process MUST use GitHub Issues.
- All feedback from non-ToIP members MUST use the Feedback license as specified by the Joint Development Foundation.
- The group MUST publish a ToIP blog post announcing the public review, explaining the background and purpose of the deliverable, and providing instructions on how anyone (both ToIP members and non-members) can provide feedback during the public review period.
- The ToIP Executive Director MUST send a notice of the public review to the ToIP Steering Committee.
- The group MUST process all feedback received by either incorporating it into the deliverable or explaining why it was not incorporated by posting one or more responses to the GitHub issue.
Stage 10: WG Approved Draft
Once the public review is complete and all issues raised have be processed and responded to, the group is ready to submit the deliverable to the Working Group as a Working Group Approved Draft. This approval MUST be given either through:
- A formal call for consensus at a regularly scheduled meeting of the Working Group at which at least one week's notice has been given of the planned vote, OR
- An email call for consensus on the Working Group's mailing list that is open for at least seven days.
If either call for consensus receives an objection which cannot be resolved via discussion, then the Working Group must hold a formal ballot (following the same rules above). To be approved, a majority of Working Group members MUST vote in favor of approving the deliverable.
Stage 11: ToIP Approved Draft
Once a deliverable is approved as a Working Group Approved Draft, the Working Group MAY elect to submit it to the ToIP Steering Committee for approval as a ToIP Approved Draft.
If a majority of the Working Group is in favor of that step, the Working Group chair(s) MUST notify the ToIP Executive Director of the submission at least two weeks in advance of a ToIP Steering Committee (SC) meeting.
After receiving notice, the SC MAY choose to take up to 30 days to hold a call for consensus to approve the deliverable.
If consensus is not achieved, the Steering Committee MUST hold a formal ballot. To be approved, a majority of Steering Committee members MUST vote in favor of approving the deliverable.