Find JSRs
Submit this Search

Ad Banner

The Life of a Spec Lead:

Part III, Cycling Through the Draft Reviews

*Writing the Early Draft Review*

In the life cycle of a JSR, the EDR is the first major technical milestone that an Expert Group works towards. JCP members and the public look forward to this review cycle because it offers a first clear look at what the specification will include. Spec Leads also anticipate this stage. They gain valuable early insights into the Java community?s expectations, needs, and wishes from the feedback they receive. This important step helps ensure that the final standard actually reflects the requirements of the market.

Spec Leads have plenty of leeway in determining when to release an EDR, but getting feedback earlier allows an Expert Group time to build in features when and where they make sense.

Mark Hornick is a senior manager in Oracle?s Data Mining Technologies group. Now recognized as a Star Spec Lead, Mark is responsible for JSR 73, Data Mining API, and JSR 247, Data Mining 2.0. He feels the Expert Group should work quickly to get to the EDR stage "within the first year of the Expert Group's formation. As the journey of a thousand miles begins with a single step, the creation of a complete specification begins with the writing of a single word." However, coming up with the EDR is not a simple endeavor. "Ideally, the Early Draft reflects a reasonably well thought out architecture and design that can be tweaked rather than rewritten," says Mark. "The EDR pushes the Expert Group to get a consensus on the basic features and aspects of the standard and put even a strawman before the user community for feedback."

Sometimes the release date of an Early Draft is affected by which pieces a Spec Lead prefers to include. Jose Cronembold is a senior development manager at Oracle and a Star Spec Lead. He led JSR 198, A Standard Extension API for Integrated Development Environments. Jose believes it is best to release an EDR only after the classes and interfaces are coded and javadoc'd. Before EDR, Jose concentrated on finalizing a draft of the specification document, which incorporated the javadoc as an integral part. His EDR also included the source code.

Mark agrees, "The major classes and interfaces should be included with sufficient detail to understand what is being proposed. The JSR 73 CDR and JSR 247 EDR included a prose document as well as Java interface definitions and preliminary javadoc." He also notes that the EDR should define the purpose of the JSR, the audience, and the architecture, framework, and design that will govern the specification.

Linda DeMichiel is chief architect for Enterprise JavaBeans (EJB) and Java Persistence at Sun Microsystems. She is also a Star Spec Lead, having led JSR 19, EJB 2.0; JSR 153, EJB 2.1; and JSR 220, EJB 3.0. Linda says that an EDR should be published when the draft is solid enough, laying out a clear direction while open on details, to draw the kind of attention from the market that validates the direction and prompts feedback.

*Generating Feedback on the EDR*

When the comments on the EDR start rolling in, it's easy for a Spec Lead to feel defensive, yet Jose says the key to conducting a successful EDR is to be objective and open to feedback. "You need to address all meaningful issues raised by reviewers, and if necessary incorporate missed requirements in your design." Most of the responders to Jose's EDR represented companies that had a serious interest in seeing the APIs addressed by JSR 198 become standard.

Although anyone is welcome to respond to an EDR, those with some sort of stake in the outcome are more likely to take the time to review and comment on the draft. "We had a range of responders, from students specializing in the field to individuals from companies interested in the topic," says Mark.

In general, the more Expert Group members work on a JSR, and the higher the version number for a JSR, the more responses an EDR will evoke from the community. That's because the number of Expert Group members is already a rough measure of community interest in the technology, and attention tends to rise as a technology passes through each new final version and gains traction in the market. For example, the Expert Groups led by Jose, Linda, and Mark included 13 to 21 members, except for 30+ member Expert Group for JSR 220, the third version of EJB.

Predictably, the EDR for JSR 220 mustered a lot more response than the others did. However, Linda and her colleagues took extra steps to shake out a greater response from the industry, using every opportunity to solicit feedback. The results were phenomenal, evoking several hundred feedback messages over the course of the JSR. "We got a lot of validation on what we were doing because the community was very excited," Linda says. "I think a lot of the feedback was from individual developers rather than from members involved in the JCP program. Comments came in from people all over the world, in universities and industry, so I'm glad we had that openness at the early stages." Her Expert Group found the process so helpful that they released an optional second EDR to get more feedback "on some of the drill-down on items we had looked at in the first EDR."

In contrast, Mark's EDR elicited about a dozen emails from outside of his Expert Group, and Jose's EDR netted approximately twenty email threads. Mark says, "Most of the feedback came from within the Expert Group although we also received insightful comments from a few non-EG reviewers."

*Collecting and Addressing Feedback*

In releasing their EDRs, Mark and Jose had fairly specific agendas. Mark sought comments on the scope -- the selection of features -- and the basic architecture or design patterns that had been selected for ease of use. Moreover, his Expert Group sought feedback on issues pertinent to the topic of the JSR, such as specific settings for data mining functions and algorithms, as well as various data mining tasks.

Jose was looking to stir up something quite different. He wanted others to provide feedback and even contribute new ideas in order to generate interest and a sense of ownership in the project.

It's important for the Expert Group to be aware of comments on the EDR. Jose simply forwards the feedback to the group's email address. He also takes responses to the early draft seriously, following up on all submitted comments. He answers questions and addresses issues by revising whatever needs to be changed. "In cases where feedback requires careful consideration, I open it for Expert Group discussion and decide if the specification needs to be updated," he says.

Mark created a public project at, 'datamining,' where the public can post questions and get answers, as well as an alias so that emails can be sent directly to the Expert Group. More proactively, Mark raises the issues that have come to light from feedback during conference calls and at face-to-face meetings.

Linda set up a series of rolling feedback aliases to channel community feedback directly into the full Expert Group and foment discussion. She'd keep a feedback alias open "until it got so much spam that by then the next draft would be out." Then she'd close the previous edrfeedback feedback alias and open a new one, which she called edr2feedback, and so on. "Having different names for them helped you know who was paying attention to what was on the spec and actually downloading the new spec and sending feedback on that draft," she says.

*Preparing for the Public Draft Review*

Mark looked at the EDR process as "a dry run that helps get the basic framework in place for producing the Public Draft and Final Draft." The Public Draft Review (PDR) has a lot more riding on it than the EDR, namely the approval of the Executive Committee (EC). The EC, consisting of major stakeholders and a representative cross-section of the JCP community, serves as a gatekeeper for JSR activity. During the PDR, the Executive Committee (EC) votes "Yes" or "No" on whether an Expert Group should publish a revised draft after PDR, and whether the group should continue with the development and release of the Technology Compatibility Kit (TCK) and Reference Implementation (RI).

Hani Suleiman is an individual member serving on the EC. During Hani Suleiman's one-year tenure on the Java Standard Edition/Enterprise Edition EC, zero No votes have occurred during PDR. He says that if a No vote is cast on a rare occasion, it is almost never over a technical issue, but for licensing or political reasons. "If the issue is technical, then it's likely that the EC rep will vote "Yes," and then take it up with the Spec Lead, asking them to address the issue in the next iteration of the spec."

The EC accesses the same materials that are presented in the normal EDR and PDR packages. EC comments on drafts of the JSR have been reasonable, Mark says. "Our experience with the EC has been very positive. In the past, we received a few minor comments during the ballots, but nothing has caused us to make major changes in the specification. When we had questions about some of our unconventional approaches to the RI and TCK, we received timely approval in advance."

The PDR is similar to the EDR in that the public as well as the JCP community can download and comment on both drafts. However, by the time the Public Draft is released, the specification is pretty much set. It is unlikely at that late date that the Expert Group would immediately address any wishes for less critical features, but would instead create a list of what could be added in future versions.

The EDR and PDR both push the standard forward. "Each draft release is a visible milestone that says 'we're getting closer,'" says Mark. For a PDR to succeed, the Spec Lead may need to prod the Expert Group to produce and review the document, interfaces, and javadoc, with many iterations. He says, "By the time the EDR is released, many of the details for the specification have been worked out, and the public can see what the final specification is likely to contain. We go to PDR when we have over 80 per cent of the expected content of the standard in place. The Public Draft need not be perfect or complete."

The key words for Linda are "functionally complete -- the Public Draft may still have holes and known open issues that are called out as such." Releasing the Public Draft for EJB 3 was a major effort for Linda. Not only did the JSR integrate and build upon previous relevant APIs, it also presented a simplified developer view of EJB and specified how the current version related to EJB 2.1 architecture in a highly technical, 500-page document. Further, in addition to this 500-page EJB Core Contracts document, the Public Draft also contained separate specification documents for the Java Persistence API and for an overview of the new EJB Simplified API. Moreover, her self-imposed deadline was just before the JavaOne Conference and the EC's face-to-face meeting. "I didn't want the EC voting on 'Trust us. This is all going to fit together properly. I wanted it all there,'" says Linda.

For JSR 73, Mark's group conducted two Public Reviews for JSR 73, but one for JSR 247. They don't intend to have a second Public Review. Although the EC vote was favorable, with no recommendations for changes, "Our thinking regarding the use of interfaces, enumerations, and exceptions changed somewhat between the two JSR 73 Public Drafts, and the second was much improved," Mark says.

*Wrapping Up the Proposed Final Draft*

If all has gone well, the Expert Group incorporates all reasonable comments that were submitted during PDR. Then comes the work of squaring up all the pieces of the final package with each other. According to Linda, "The RI and the TCK and the QA cycle we go through at Sun shake out any remaining open issues or any potential bugs either in the spec or in the implementation, so that process is the final tuning of the specification."

After the RI and TCK are complete, the Proposed Final Draft makes those parts, along with the specification, available to JCP members and the public. A Spec Lead could continue getting comments for a long time. Linda notes, "We're still getting feedback from the community and from the Expert Group members. People go, 'Oh could you add this....' But at some point we have to close a specification and consider what items might be addressed in a next release."

Ultimately, the progression of a JSR through the various milestones can be nerve wracking, though of great worth to the development community and the market. Perhaps Linda sums it up best when she admits, "Producing any release, no matter how trivial, is stressful on a Spec Lead because you have to crank out something that is 'release quality' and which will bear scrutiny by the community and result in high-quality feedback. It is a lot of work to do a release, but every release is important both to the Expert Group and the Java community."

Back to part 2. ..      Go to part 4...