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.... 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/MaintUpdateComp..."

< 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...."

---

<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>₂ adds class <code>bar.Quux</code>. This < program

Then <i>L</i>₂ adds class <code>bar.Quux</code>.

Consider the following program: 679,681c688,691 < will compile under <i>L</i>₁ but <i>not</i> under < <i>L</i>₂ 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>₁ but <i>not</i> under <i>L</i>₂ 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..." 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 © 2010 Oracle Corporation and/or its affiliates. All rights reserved.

Copyright © 2010 Oracle Corporation and/or its affiliates.

All rights reserved.