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

Mon May 17 12:07:08 PDT 2010

Joe Darcy wrote:
> Hello.
>
> After receiving some off-list feedback and some additional 
> self-editing, I considering making the following changes in the next 
> draft:
>

I've posted draft 0.776 to
http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.776.html

In addition to the previously mentioned changes, this draft changes the 
URLs of the images and reflect various corrections and suggestions from 
Oracle's docs team; diff below.

-Joe

8c8
< <h1>OpenJDK Developers' Guide, Version 0.775</h1>
---
 > <h1>OpenJDK Developers' Guide, Version 0.776</h1>
116c116
< The purpose of this guide is help you, an OpenJDK developer, to discern
---
 > The purpose of this guide is to help you, an OpenJDK developer, to 
discern
122c122
< are good approaches to make progress.
---
 > is a good approach to making progress.
134,136c134,138
< done - say, adding a new package - and the release-specific
< documentation will describe <em>how</em> a task is done in that
< release, such as any needed build changes to add a new package.
---
 > done, say, adding a new package.
 >
 > The release-specific documentation will describe <em>how</em> a
 > task should be done in that release, such as any needed build changes
 > to add a new package.
233c235
< 
src="http://blogs.sun.com/darcy/resource/OpenJDK_Developers_Guide/CompatGrid.png"
---
 > src="http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/CompatGrid.png"
295,296c297,299
< <img 
src="http://blogs.sun.com/darcy/resource/OpenJDK_Developers_Guide/MaintUpdateCompat.png" 

< alt="Maintenance and Update Release Compatibility" title="Maintenance 
and Update Release Compatibility"/>
---
 > <img
 > 
src="http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/MaintUpdateCompat.png" 

 > alt="Maintenance and Update Release Compatibility"/>
356c359,360
< <img 
src="http://blogs.sun.com/darcy/resource/OpenJDK_Developers_Guide/PlatformCompat.png" 

---
 > <img
 > 
src="http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/PlatformCompat.png"
469,470c473,476
< is impractical, so evolving such APIs in this environment is quite
< constrained by comparison.
---
 > is impractical.
 >
 > So evolving such APIs in this environment is quite constrained by
 > comparison.
478c484
< is some fashion (or not) with respect to two versions of a library
---
 > in some fashion (or not) with respect to two versions of a library
512c518
< aspects; that is, the positive aspect keeping things that "work"
---
 > aspects; that is, the positive aspect of keeping things that "work"
573,575c579,583
< their binary compatibility impact.  All these changes could also be
< classified according to their source compatibility repercussions, but
< only a few of kinds of changes will be analyzed below.
---
 > their binary compatibility impact.
 >
 > All these changes could also be classified according to their source
 > compatibility repercussions, but only a few of kinds of changes will
 > be analyzed below.
660,661c668,670
< Then <i>L</i><sub>2</sub> adds class <code>bar.Quux</code>.  This
< program
---
 > Then <i>L</i><sub>2</sub> adds class <code>bar.Quux</code>.
 >
 > Consider the following program:
679,681c688,691
< will compile under <i>L</i><sub>1</sub> but <i>not</i> under
< <i>L</i><sub>2</sub> since the name "<code>Quux</code>" is now
< ambiguous as reported by <tt>javac</tt>:
---
 > The <code>HelloQuux</code> class will compile under
 > <i>L</i><sub>1</sub> but <i>not</i> under <i>L</i><sub>2</sub> since
 > the name "<code>Quux</code>" is now ambiguous as reported by
 > <tt>javac</tt>:
771c781
< This transformation is also binary incompatible.
---
 > Removing a method is also binary incompatible.
773,774c783,784
< The remaining changes to <code>Lib</code> will all preserve binary
< compatibility.
---
 > The remaining changes to <code>Lib</code> discussed below will all
 > preserve binary compatibility.
907,909c917,920
< method taking one <code>int</code> argument is selected and no
< conversion instruction from <code>int</code> to <code>double</code> is
< present to be executed before the method is called.
---
 > method taking one <code>int</code> argument is selected and there is
 > no intermediary conversion instruction from <code>int</code> to
 > <code>double</code> to convert the argument before the
 > <code>invokevirtual</code> instruction to call the method.
995c1006
< taking a <code>long</code></a> as part of
---
 > taking a <code>long</code> argument</a> as part of
1021c1032,1034
< <img 
src="http://blogs.sun.com/darcy/resource/OpenJDK_Developers_Guide/SrcCompatLevels.jpg" 
alt="Source compatibility levels of FQN programs">
---
 > <img
 > 
src="http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/SrcCompatLevels.jpg"
 > alt="Source compatibility levels of FQN programs"/>
1028c1041
< In binary preserving source compatibility, existing clients will yield
---
 > In binary-preserving source compatibility, existing clients will yield
1233,1234c1246,1248
< elements in this set. The elements are returned in no particular
< order.
---
 > elements in this set.
 >
 > The elements are returned in no particular order.
1243,1247c1257,1263
< The iterator algorithm can and has varied over the years.  These
< variations are fully source and binary compatible.  While such
< behavioral differences are fine in a platform release, because of
< behavioral compatibility they are marginally acceptable for a
< maintenance release, and only questionable for an update release.
---
 > The iterator algorithm can and has varied over the years.
 >
 > These variations are fully source and binary compatible.
 >
 > While such behavioral differences are fine in a platform release,
 > because of behavioral compatibility they are marginally acceptable for
 > a maintenance release, and only questionable for an update release.
1316c1332
< <li><p>Deletes yeoman Janice Rand
---
 > <li><p>Deletes yeoman <tt>JANICE_RAND</tt>
1319c1335
< <li><p>Adds Pavel Chekov
---
 > <li><p>Adds <tt>PAVEL_CHEKOV</tt>
1338,1341c1354,1358
< compilations.  The deletion is also binary incompatible.  Besides
< being observable via reflection, the deletion affects the behavior of
< various built-in methods on the enum, including <tt>values</tt> and
< <tt>valueOf</tt>.
---
 > compilations.
 >
 > The deletion is also binary incompatible.  Besides being observable
 > via reflection, the deletion affects the behavior of various built-in
 > methods on the enum, including <tt>values</tt> and <tt>valueOf</tt>.
1352c1369
< <li><p>Adding <tt>CHEKOV</tt> is binary-preserving source compatible.
---
 > <li><p>Adding <tt>PAVEL_CHEKOV</tt> is binary-preserving source 
compatible.
1373c1390
< <li><p>Reordering McCoy, Scotty, and Spock is a binary-preserving
---
 > <li><p>Reordering Bones, Scotty, and Spock is a binary-preserving
1484,1490c1501,1508
< For discussing the evolution policies of the JDK, the term "interface"
< will not only refer to an <code>interface</code> type but also much
< more broadly to any means by which one software component interacts
< with another software component or with a human.  This notion of
< interface covers Java SE APIs, command line options, file locations, file
< formats, network protocols, GUIs, and many other observable aspects of
< the JDK.
---
 > When discussing the evolution policies of the JDK, the term
 > "interface" will not only refer to an <code>interface</code> type but
 > also much more broadly to any means by which one software component
 > interacts with another software component or with a human.
 >
 > This notion of interface covers Java SE APIs, command line options,
 > file locations, file formats, network protocols, GUIs, and many other
 > observable aspects of the JDK.
1522,1524c1540,1543
< list iterator (with <code>listIterator()</code>). Then, it iterates
< over the list until the specified element is found or the end of the
< list is reached."
---
 > list iterator (with <code>listIterator()</code>).
 >
 > Then, it iterates over the list until the specified element is found
 > or the end of the list is reached."
1628,1630c1647,1650
< over and above the general evolution policy.  For example, some groups
< may have agreements concerning how particular unofficial interfaces
< may change over time.
---
 > over and above the general evolution policy.
 >
 > For example, some groups may have agreements concerning how particular
 > unofficial interfaces may change over time.
1692c1712
< it.
---
 > the interface.
1728c1748
< intended to assist and supplement the engineers' primary responsibly
---
 > intended to assist and supplement the engineers' primary responsibility
1772c1792
< Are contemporary language features employed wisely?
---
 > Are contemporary language features being employed wisely?
1808a1829,1840
 >
 > 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.
 >
1841,1842c1873,1874
< C, C++, shell, and so on; these preferences extend to encompass
< writing regression tests.</p>
---
 > C, C++, shell, and so on; these preferences extend to writing
 > regression tests.</p>
1899c1931
< extant of the change.
---
 > extent of the change.
1914a1947,1961
 > <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>
 >
1917c1964
< <p>Thou shalt write regression/unit tests to accompany one's JDK
---
 > <p>Thou shalt write regression/unit tests to accompany thy JDK
1961,1964c2008,2015
< Using the annotation places more of the semantics of the code in the
< source code proper as opposed to a comment while using the javadoc tag
< allows alternate functionality to be recommended along with the
< specification for the element.
---
 > Using an annotation to formally indicate deprecation declares the
 > semantics of the code in the code itself, as opposed to the previous
 > practice before annotations were available of marking deprecation with
 > a comment.
 >
 > Using a paired <code>@derepcated</code> javadoc tag for informative
 > purposes allows the deprecation to be explained and any alternate
 > functionality recommended.
1990c2041,2043
< Copyright &copy; 2010 Oracle Corporation and/or its affiliates. All 
rights reserved.
---
 > Copyright &copy; 2010 Oracle Corporation and/or its affiliates.
 >
 > All rights reserved.