Working on the Specification
- Stefan Meissner
One of the core tasks of the CIP4 Consortium is working on the JDF / XJDF Specification. Thus, the specification process belongs to the core process of the committee. This document describes how to work on the specifications such as modifications, clarifications, extensions as well as bug fixing. Generally, everyone (members and non-members) should be able to start a discussion about any topic in the CIP4 Specifications.
Quickstart
TBD
The Specification Process
The Specification Process starts when a new issue has been created in a specification project in JIRA. There is one project per individual CIP4 Specification in JIRA (see JDF, XJDF, PrintTalk). You can easily create a new issue by pressing the "Create" button on the very top position in JIRA.
The following you can see the workflow diagram of how specification issues are processed at CIP4. Roughly, the workflow consists of two main parts. The "Discussion and Drafting"-Part and the "Editing and Verification"-part. The first part includes the process steps from "Discussion" to "TSC Approve" whereas the second part starts with the "Specification" status and ends when the issue is "Implemented".
Discussion and Drafting
The first part of the process is about discussion and drafting. As mention above, every registered user (members an non-members) is able to improve, extend, clarify or bug-fix our specifications by creating a issue in the appropriate JIRA Project (see JDF, XJDF, PrintTalk). Below, a detailed list of all status in the "Discussion and Drafting" part with their specific meaning.
| Status | Description |
|---|---|
| DISCUSSION | "Discussion" is the initial status of each issue. In this status people can discuss about the modifications suggested in the specific issue. The goal is to get a broad and deep view on all the effects affected by the changes. Also, the integrity of the whole specification has to be considered and ensured at this point. |
| WG APPROVE | When the discussion is completed, the suggested changes has to be approved by a work group. Work group meetings are normally organized biweekly. A work group is able to push the issue back in status "Discussion", if some more details or clarifications are required. When the changes are reasonable the issue is going to be approved and is ready for drafting then. In rare cases an issue can also be reject by the work group. |
| DRAFTING | In "Drafting" the modifications have to be prepared for the specification. Changes on the text, wordings, images, sketches have to be finalized and attached to the JIRA Ticket. You can also use Confluence for drafting and link the appropriate page in the JIRA Ticket. The result has to be an excerpt of the specification which already includes the changes. This excerpt is the one-by-one blueprint for the editor when modifying the specification. |
| TSC APPROVE | The final excerpt has to be approved by the Technical Steering Committee (TSC). The TSC is responsible for the integrity of the whole specification and has to approve each individual change on the specifications. As work group meetings, TSC meetings are also scheduled biweekly. |
| REJECTED | All rejected issues have the status "Rejected". "Rejected" is a passive status and represents the history of already discussed and rejected issues. We want to safe time by avoiding redundant discussions. Nevertheless, rejected issues can be reactivated an bring back to status "Discussion" at each time. |
Issue Types
| Issue Type | Description |
|---|---|
 Story | The Issue Type "Story" is used for most modifications, improvements and extensions in the specifications. Stories are used to be manageable and not too complex. Most issues should be stories. |
 Epic | Epics are larger themes or topics that consists of multiple stories each. An epic does not follow a workflow. It is completed once all attached stories are completed. |
 Bug | Bugs in JDF 1.5 are intended to be published in JDF 1.5 Errata. They are additionaly fixed in the next version of the specification. Bugs in unpublished specifications are simply fixed in the master document. |
Editing and Verification
The second part of the specification process starts after the approval of the Technical Steering Committee (TSC) . Issues are going to be implemented in the master document and the XML Schema of the appropriate specification. The TSC has to verify the modifications in the master document and in the XML Schema before the issues are marked as implemented.
| Status | Description |
|---|---|
| SPECIFICATION | The status "Specification" implies that an issue is ready for being implemented into the specification. The Specification Editor has to transfer the approved draft of the modification to the master document of the specification one by one. The editor has also to transfer the attachments if required. Are you interest in getting involved as CIP4 Specification Editor? |
| SCHEMA | Most modifications in the specification do also affect the XML Schema. The XML Schema Editor is responsible to update the XML Schema for an issue. |
| TSC VERIFY | The TSC has to verify and approve the changes in the specification and XML Schema once the modifications of an issue have been implemented. |
| IMPLEMENTED | The issue has been implemented and is part of the official (next) specification now. |
Release Management
In all matters of intellectual property rights and procedures, the intention is to support and promote Specifications while respecting the legitimate rights of intellectual property owners. Thus, publishing a new version of a Specification is a longer-term process:
| Period | Description |
|---|---|---|
| Initial Review | 60 days | The publication of a new version starts with a 60 days "Initial Specification Review" exclaimed by the CIP4 Chief Technical Officer (CTO). Within this period, each Member participating in the development of the new Specification shall give, for all patent claims necessary to implement any area of the new Specification. |
| Call for Changes | 30 days | Next, a 30 days period “Call for final changes to the draft” is called by the CTO. During that period all Members are encouraged to review the working draft for patent claims that they may hold that are necessary for the implementation of any area of the Specification. |
| Spec Review | 45 days | After reviewing the suggested changes received from any Member and incorporating such revisions as deemed reasonable, the CTO will submit the final working draft for approval by the Technical Steering Committee and all working group members for comments and IP review within a specified period which shall be not less than 45 days. |
| Final IP Review | 60 days | A final draft of each proposed Specification will be distributed to all Members for review not less than 60 days prior to final acceptance and publication of such Specification. |
All in all, the publication of a new Specification takes almost 200 days. The full publication process is described here: /wiki/spaces/TSC/pages/1557168718.
Errata
TBD
Info
This document is still under process.