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 Implementers Draft or Public Review Draft |
| 8 | Implementers Drafts | OPTIONAL for technical specifications where implementation feedback is desired prior to finalization. | Consensus that sufficient implementation feedback has been 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 have been started based on 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 page 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., 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 actively use to implement and provide feedback. 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 labeling a specification as 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 Working Group or Task Force (either can trigger a public review draft) feels it has received sufficient implementation feedback—then the Working Group or Task Force 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 a ToIP GitHub repo (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 All-Members mailing list and 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 the Working Group or Task Force has responded to all issues raised, the deliverable is ready to be submitted to the Working Group for approval as a Working Group Approved Draft. This approval MUST be given either via:
- A formal call for consensus at a meeting of the Working Group for which at least one week's notice has been given of the planned vote, OR
- An email call for consensus sent to the Working Group's mailing list that allows at least seven days for any WG member to reply with an objection.
If no objections are received via either method of calling for consensus, the deliverable is approved. If a 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 at a meeting of the Working Group, a majority (51%) of Working Group members present MUST vote in favor of approving the deliverable. To be approved via an email ballot, a majority (51%) of Working Group members on the mailing list 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 the deliverable 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 a total of 30 days to hold a call for consensus for approving the deliverable.
If consensus is not achieved, the Steering Committee MUST hold a formal ballot. Formal ballot rules for an SC vote follow the same rules as for a WG vote.