 |
Home | Changes | Index | Search | Go
Introduction
Welcome to the SwingLabs API Review page. This page contains links to each component in a SwingLabs project which has been or is
in process of being reviewed. Following is an overview of the review process, including the motive.
Motive
To provide a stable set of components that will make future additions to the codebase significantly easier to accept from outside parties by making the process as transparent and clear as possible. To provide a more straightforward path for outside contributors who want to get their code committed to the main swingx tree. To provide a stable set of components to users, with clear expectations for which code is stable and which code is still in development.
Process
There is code in SwingX? and the other subprojects in various states of completion. Most of that code has not gone through a complete review process, and as such cannot be considered as stable code. The API review process is designed such that in the end, these components can be considered stable. The API review is also such that if the component were going to make it into the JDK, it could do so with the minimal amount of work or change to API.
The first step is to prepare a component (or framework) for review. Whoever accepts responsibility for "championing" a component through the review process begins by updating the API to match what he/she thinks is the best possible API. This may mean working on a development branch instead of the main trunk if changes are significant. Updating the API also includes updating the documentation (JavaDoc? is considered the "spec" in Java). Once the JavaDoc? and API design phase is finished, the submitter will prepare some output for review (typically this is either the source code itself in some modified form, or the JavaDoc? HTML).
The next step is an internal review at Sun Microsystems with the Swing team. We will review the API and documentation. From this review will come a list of suggestions and issues for the submitter to review. This process repeats until the submitter and Swing team are content with the API. The review process is then opened up to the community in general. Begin by posting a "XXXComponent ready for external review" message on the forums. Include a link to the documentation to review, and also a link to the results of previous reviews (these should all be available from here in this wiki). Once the component has gone through the external review process, it is ready to be marked as "@status = Reviewed" in the class documentation.
The next step for the component (if it has not already been done) is to write comprehensive unit tests and tutorial documentation. By "comprehensive" we mean: the unit tests must pass Jeanettes muster (our resident Unit Test advocate). JavaDocs must be complete (all tags where the belong, written according to Sun's guidelines How to Write Doc Comments for the JavaDoc Tool?. Further ideas are collected in JavaDoc Notes ). Tutorial docs must exist on swinglabs.org according to Josh Marinacci's standards (our resident writer).
Reviews can be lengthy. This is partly why we do a review here at Sun, and publish the materials and findings to that review in the wiki. The idea is that all minor issues will shake out during the internal review and make for a more expeditious public review. The other reason is so that code that does migrate to the JDK won't have to be entirely redesigned.
Question: What I'm still not quite clear about is what are the criteria for an "api review"?
The first requirement is a piece of code that is ready to be defended. What we don't want to do is to devolve into a design-by-committee review, which is what happens to poorly or incompletely thought out API. It's ok to go into it with a few open questions, but we also need to have a suggested solution to think about.
Also, expect that even the most trivial code (like JXPanel) is going to be revised during the process. In a successful review a year and a half ago (or thereabouts) Bino brought in the authentication framework. It looked different afterward, but has essentially been stable since.
Be prepared to defend why a certain design was taken. Why not one of several alternative designs? What makes the proposed solution better? More complicated API needs to be more rigorously defended, particularly with why the complicated API was chosen. Are the use cases enabled by the more complex API worth it?
Of course a list of requirements up front is critical. What are we trying to achieve with this API? If the requirements are off, the review will most likely be postponed until the requirements are refined and API refined as necessary.
Reviews
Collection Components
That's my favourite name to denote components for showing collection-type data like lists, trees, tabular data.They allow a rich
user-interaction which is fully configurable by developers. They support advanced interaction themes (like f.i. sorting, searching)
in a consistent manner. This leads to a huge api which has to be broken down into bounded clusters to be manageable for
review. The approach I'm using in review preparation is bottom up:
- starting from the lightweight, widget-targeted classes (example: TableColumnXX)
- to usage of those collaborators by the widget (example: JXTable api related to the enhanced TableColumnXX).
- after that: - from cross-component collaborators (example: Highlighter)
- to usage of those collaborators by a sample widget (JXTable api related to highlighter)
- to analogous usage by the other interested widgets (JXList, JXTree api related to highlighter)
Component support
Cross-component themes
|