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—recommended 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: "Pre-Draft", "Draft", "Working Group Approved", and "ToIP Approved" deliverable.
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.
When the group is ready to begin drafting, it must decide which collaboration tools it will use. ToIP offers two choices:
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. Note, however, that this option is not yet supported by our Terminology Engine tools (produced by our Concepts and Terminology WG) for automatic linking/annotation of glossary terms (see below).
Guidelines:
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 date-stamped 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.
Guidelines:
Regardless of whether Google Docs or GitHub Markdown is used, the document should carry the subtitle "Working Draft" followed by a two-digit number representing the Working Draft version, starting with 01. For example: "Working Draft 01", "Working Draft 02", "Working Draft 03", etc.
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.
The document should carry the subtitle "Implementers Draft" followed by a two-digit number representing the Implementers Draft version, starting with 01. For example: "Implementers Draft 01", "Implementers Draft 02", "Implementers Draft 03", etc. The Implementers Draft version numbering is entirely independent of the Working Draft version number. For example, your group could transition from "Working Draft 07" to "Implementers Draft 01".
Before a Working Draft or Implementers Draft can be submitted for approval as a Working Group Approved Draft, it MUST be subject to at least one public review of at least 15 days (30 to 60 days is RECOMMENDED). Either a Working Group or Task Force can trigger a public review draft. If the deliverable is a technical specification, it is RECOMMENDED to wait until the group has received sufficient implementation feedback. For any other deliverable, it is up to the group to decide when the deliverable is ready for public review.
Guidelines:
Once 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 via a formal call for consensus using one of two options:
If no objections are received during the call for consensus, the deliverable SHALL be 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.
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 (SC) for approval as a ToIP Approved Draft.
If a majority of the Working Group is in favor of that step:
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.
The following diagrams are intended to help understand the process by which the various deliverables move through the JDF and ToIP deliverable processes.
The LF/JDF system recognizes the following deliverables:
The "Pre-Draft" stage does not form a deliverable yet, but the stage is critical in forming a deliverable.
This is the workflow that has the longest period of work - both technically and socially. It is all about getting the deliverable into a formal state. Depending on the deliverable type this process may be relatively lightweight (e.g. whitepaper) or very heavyweight (e.g. specification).