Draft of restarted "OpenJDK Developers' Guide" available for discussion

[Joe Darcy]

Hello.

After receiving some off-list feedback and some additional self-editing, 
I considering making the following changes in the next draft:

Addendum to the section on efficiency:

1808a1809,1820
 >
 > When trying to measure efficiency, beware meddling with
 > micro-benchmarks!
 >
 > Popular JVM implementations are dynamic environments which make
 > measuring small performance differences with micro-benchmarks a subtle
 > task, quick to cause anger.
 >
 > Also, between several possible alternative codes, the alternative
 > which performs best on a particular JVM implementation may not perform
 > best on other JVM implementations of interest.
 >


Typo fix:

1899c1911
< extant of the change.
---
 > extent of the change.


More on general logistics of code reviews:

1914a1927,1941
 > <p>
 >
 > While revewing patch files is adaquate for small changes, larger
 > changes are often facilated by use of <a
 > href="http://blogs.sun.com/jcc/resource/webrev">webrev</a>.
 >
 > The webrev script produces a set of HTML pages providing multiple
 > views of the change.
 >
 > The change is presented as various flavors of <a
 > href="http://en.wikipedia.org/wiki/Diff">diff</a> output as well as
 > original and new versions of each modified file.
 >
 > </p>
 >

-Joe

joe.darcy at oracle.com wrote:
> Greetings.
>
> I've been working on a restarted version of the "OpenJDK Developers' 
> Guide" and I have a draft far enough along for general discussion.  
> The content of the existing guide [1] is primarily logistical and 
> procedural in nature; in time, I plan to migrate this information to a 
> JDK 7 specific page because many of the details are release-specific.  
> The new guide is more conceptual and once completed is intended to be 
> able to last for several releases without major updating.
>
> The table of contents of draft version 0.775 is
>
>    * Preface
>    * OpenJDK Development Motto
>    * Kinds of Releases
>          o General Evolution Policy
>    * Kinds of Compatibility
>          o Source Compatibility
>          o Binary Compatibility
>          o Behavioral Compatibility
>          o API Compatibility Case Study
>          o Other Kinds of Compatibility
>          o Managing Compatibility
>    * Kinds of Interfaces
>          o What is an interface?
>          o Specification = Syntax + Semantics
>          o Official and Unofficial Interfaces
>          o Importing and Exporting Interfaces
>    * Developing a Change
>          o Coding Guidelines
>          o Source Code Management
>          o Code Reviews
>          o Regression and Unit Tests
>          o Deprecation
>    * TODO
>
> The full draft is available from:
> http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/
>
> The compatibility sections are currently more fully developed than the 
> ones about developing a change.
>
> All level of feedback is welcome, from correcting typos, to stylistic 
> suggestions, to proposals for new sections.
>
> Initially, I plan to maintain the guide as an HTML file and publish 
> new versions as needed.  Over time, guide maintenance may transition 
> to more formal version control, such as a small Mercurial repository 
> or a wiki.
>
> Thanks,
>
> -Joe Darcy
>
> [1] http://openjdk.java.net/guide/