Downloads: Making Drafts and Collateral Available
By Susan Mitchell
Within the Java Community Process (JCP) Program, there has been a growing conviction that transparency is critical for success. The JCP Program requires that every Java Specification Request (JSR) be published as an Early Draft, Public Draft, Proposed Final Draft, and Final Release. However, a few Expert Groups are comfortable with a degree of transparency that allows them to publish drafts more regularly than is required, even though they might be incomplete or buggy.
The community can offer input as soon as a JSR's description is posted, but it's not until a draft of the specification is published that discussion really takes off. Moreover, having an entire draft to examine, and then multiple drafts to compare, enables contributors to make better-informed suggestions, corrections, and recommendations. Reviewers can also see how their contributions have influenced the Expert Group's effort.
Here are brief case studies of praise-worthy Expert Groups that are making drafts available to the community more often than required:
170 and 283 hosted on the JCP program's site. However, far more information is available at the related open-source webpage, jackrabbit.apache.org/, or at jsr-283.dev.java.net/, where the actual work gets done. (The package space of JSRs 170 and 283 is javax.jcr, hence the use of codename JaCkRabbit on the Apache Software Foundation site, to match the other animal codenames already in use, such as "Tomcat"
The whole point of a JSR effort is to produce an Application Programming Interface (API), Reference Implementation (RI), and Technology Compatibility Kit (TCK) that will be used as an industry standard. Anyone can look into the downloads section to retrieve those pieces and see how they are progressing. These downloadable materials are updated, even more often than during the formal review periods -- Early Draft Review, Public Review, Proposed Final Draft, and so on -- mandated by the JCP program.
David has acted for quite some time upon his long-held conviction that "transparency is a topic of great importance." In the earlier years when the JCP program was less forceful in requiring a transparency plan, JSR 170 still made content openly available at http://jcr.day.com/.
David has seen the most benefit come from making the RI available to the public. He says, "I can definitely recommend that Spec Leads do a true open source community-based Reference Implementation since that's really where most of the feedback comes from."
For those with an eye on the ultimate JSR output, what's most compelling about this Expert Group's transparent approach is the constant availability of a current draft of the specification when most Spec Leads offer updates only during the review periods mandated by the JCP program. In contrast, Mike and Alex update public drafts of the specification monthly. Historical information is preserved through three detailed changelogs, which supply links to previous versions of the specification, Reference Implementation (RI), and Checker Framework. "The changelog has been critical in getting people to read new versions of the specification. No one is willing to read a long document once a month, but people want to know what has changed," says Mike. The RI is also available, in binary and source formats, and updated approximately every three weeks.
In making frequent releases and running an open mailing list, the co-Spec Leads had two goals: to elicit feedback and demonstrate progress. Mike knows how easy it is for people, especially non-language-designers, to misinterpret a language specification. He hoped to get plenty of feedback to help them improve the specification. "I wanted to understand all the ways in which someone could misunderstand or criticize the JSR, and to understand all the ways in which the JSR was imperfect and could be improved. A closed process among a small Expert Group is unlikely to generate as many ideas or expose as many flaws as an open process," he says. he says. In fact, Mike says that as a result of making the public drafts, he "received a wealth of extremely useful ideas for improving both the design and the way the specification describes it. Even the most critical comments helped me to refine the specification."
Proving that the JSR was making forward progress was also important, and the co-Spec Leads used the mailing list to help get the word out. "Many JSRs seem to peter out; others lie dormant for years, and it's hard to tell the difference. I didn't want anyone to get the impression that JSR 308 was dying or dead," says Mike. When an Expert Group is run with this level of transparency, such misunderstandings are far less likely to occur.
The Program Management Office (PMO) and Executive Committees (ECs) began to push for increased transparency in the JCP program. Mike was eager to experiment with a completely transparent approach to running JSR 308, and he has been pleased with the results. He says, "I hoped to show that it could be done and thus inspire more transparency from other Spec Leads."
Stephen and Michael Nascimento, both individual JCP members and co-Spec Leads of JSR 310, Date and Time API, are committed to transparency, and their enthusiasm is as practical as it is contagious. They spell out their creed right up front on the introduction to their webpage: "This JSR is run in an open manner with as much activity as possible conducted here in public. Everyone is entitled to get involved, either directly in the discussion on the mailing list, by reviewing code and javadoc, via blogs or on the wiki."
Not only is everyone "entitled" to get involved, but Stephen and Michael really, really, really hope lots of people will jump in with both feet. "Without feedback, you get things wrong. You need to hear peoples opinions, and be willing to change. The more drafts the better," says Stephen. "Our aim is to produce the best API we can. And once published it can't be changed. So, lots of refining drafts is a good thing."
The best input comes when there is a clear view of the Expert Group's output. Thus, Michael and Stephen publish javadoc releases -- the bulk of the specification -- at the end of each major piece of work on the API for anyone to look at and comment on. If no work is performed on the code, then no update to the javadoc is published. These irregular releases occur more often than the JCP program's requirement for formal review purposes.
Anyone can access these javadoc files by just clicking a link on the JSR 310 website at java.net. Stephen says, "We always intended to run the JSR as an open source project. That naturally means public code, and feedback. Collecting the feedback is easier if people can access it by the method they are most familiar with -- javadoc." Some Spec Leads may be reluctant to run their projects as openly as this, but Stephen has no qualms at all. He says, "It's often thought that being open will increase the mails and issues you have to deal with. The reality is that you tend to have to address the real issues earlier than you might otherwise have to, and that is a very good thing."
JSR 321 uses the formal webpage on the jcp.org site to explain the JSR proposal, update the schedule, and offer downloads for each review cycle. However, the Expert Group's Community Update page is used in an unexpected way -- to propel JCP members to a second website at java.net. Anyone who is willing to register and log in is welcome to participate in the JSR 321 project maintained at java.net.
One of the many transparency services offered by java.net is the public Subversion (SVN) repository. SVN is a convenient tool that enables collaboration between the Experts. Moreover, any registered, logged-in person can check out a draft from the repository. Thus, they have access to the latest drafts of the source code and can exchange other documents, without regard for where the JSR happens to be in the JCP program's review cycle. "Such a repository is an essential tool for any agile design process, including what we are implementing with JSR 321. Repositories have recently grown to be a standard part of any project. If we had not had one at java.net, we would have created one on our own, but we did not want to waste resources on system administration," says Ronald.
The Expert Group has also set up a Wiki, which they use in a similar way. However, unlike the public repository, the Wiki includes a restricted area, where background information and private meeting minutes are posted away from the public eye. A private mailing list provides another place for internal eyes only discussions. "We protect the privacy of Expert Group members and their companies' intellectual property, but not the results or any intermediate steps of the JCP specification work," says Ronald. He hopes that other Spec Leads will realize that "free and open design might be a good idea for most security architectures."
Go to Spec Lead Guide