From joe.darcy at oracle.com  Fri May  7 14:35:04 2010
From: joe.darcy at oracle.com (joe.darcy at oracle.com)
Date: Fri, 07 May 2010 14:35:04 -0700
Subject: Draft of restarted "OpenJDK Developers' Guide" available for
	discussion
Message-ID: <4BE48788.40909@oracle.com>

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/

From joe.darcy at oracle.com  Wed May 12 08:55:35 2010
From: joe.darcy at oracle.com (Joe Darcy)
Date: Wed, 12 May 2010 08:55:35 -0700
Subject: Draft of restarted "OpenJDK Developers' Guide" available for
	discussion
In-Reply-To: <4BE48788.40909@oracle.com>
References: <4BE48788.40909@oracle.com>
Message-ID: <4BEACF77.509@oracle.com>

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/


From joe.darcy at oracle.com  Mon May 17 12:07:08 2010
From: joe.darcy at oracle.com (Joe Darcy)
Date: Mon, 17 May 2010 12:07:08 -0700
Subject: Draft of restarted "OpenJDK Developers' Guide" available for
	discussion
In-Reply-To: <4BEACF77.509@oracle.com>
References: <4BE48788.40909@oracle.com> <4BEACF77.509@oracle.com>
Message-ID: <4BF193DC.6080705@oracle.com>

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.


From joe.darcy at oracle.com  Fri May 28 08:09:44 2010
From: joe.darcy at oracle.com (Joe Darcy)
Date: Fri, 28 May 2010 08:09:44 -0700
Subject: Draft of restarted "OpenJDK Developers' Guide" available for
	discussion
In-Reply-To: <4BF193DC.6080705@oracle.com>
References: <4BE48788.40909@oracle.com> <4BEACF77.509@oracle.com>
	<4BF193DC.6080705@oracle.com>
Message-ID: <4BFFDCB8.8050300@oracle.com>

Joe Darcy wrote:
> 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
>

Another round of minor changes in draft 0.777:
http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html

Diffs below.

-Joe


< <h1>OpenJDK Developers' Guide, Version 0.776</h1>
---
 > <h1>OpenJDK Developers' Guide, Version 0.777</h1>
236c236,237
< alt="Compatibility Axes" title="Compatibility Axes"/>
---
 >   alt="Compatibility Axes"
 > title="Compatibility Axes"/>
299c300,301

< alt="Maintenance and Update Release Compatibility"/>
---
 >   alt="Maintenance and Update Release Compatibility"
 > title="Maintenance and Update Release Compatibility"/>
361c363,364
< alt="Platform Release Compatibility" title="Platform Release 
Compatibility"/>
---
 >   alt="Platform Release Compatibility"
 > title="Platform Release Compatibility"/>
582,583c585,586
< compatibility repercussions, but only a few of kinds of changes will
< be analyzed below.
---
 > compatibility repercussions, but only a few kinds of changes will be
 > analyzed below.
633c636
< when keywords were added (<tt><a
---
 > when keywords were added (<code><a
635c638
< title="JLSv3 &sect;8.1.1.3 &ndash; strictfp 
Classes">strictfp</a></tt>, <tt><a
---
 > title="JLSv3 &sect;8.1.1.3 &ndash; strictfp 
Classes">strictfp</a></code>, <code><a
637c640
< Assertion Facility">assert</a></tt>, and <tt><a
---
 > Assertion Facility">assert</a></code>, and <code><a
640c643
< Enhanced for loops and Static Import">enum</a></tt>).
---
 > Enhanced for loops and Static Import">enum</a></code>).
691c694
< <tt>javac</tt>:
---
 > <code>javac</code>:
713,714c716,717
< reuse "<tt>String</tt>", "<tt>Object</tt>", and other names of core
< classes from packages like <tt>java.lang</tt> and <tt>java.util</tt>
---
 > reuse "<code>String</code>", "<code>Object</code>", and other names 
of core
 > classes from packages like <code>java.lang</code> and 
<code>java.util</code>
1034c1037,1038
< alt="Source compatibility levels of FQN programs"/>
---
 >   alt="Source compatibility levels"
 > title="Source compatibility levels"/>
1115c1119
< title="Java SE 6 Specification for 
AbstractMethodError"><tt>AbstractMethodError</tt></a> is thrown; if
---
 > title="Java SE 6 Specification for 
AbstractMethodError"><code>AbstractMethodError</code></a> is thrown; if
1148c1152
< defining a proper <tt>equals</tt> method in a class can be nontrivial.
---
 > defining a proper <code>equals</code> method in a class can be 
nontrivial.
1164c1168
< structure of libraries, such as adding new <tt>public</tt> methods, is
---
 > structure of libraries, such as adding new <code>public</code> 
methods, is
1168c1172
< up the set of <tt>public</tt> methods on a library class and throw an
---
 > up the set of <code>public</code> methods on a library class and throw an
1192c1196
< included in its specification; for <tt>final</tt> classes this
---
 > included in its specification; for <code>final</code> classes this
1263c1267
< a maintenance release, and only questionable for an update release.
---
 > a maintenance release, and questionable for an update release.
1329c1333
< Compared to the first reason, the second season:</p>
---
 > Compared to the first season, the second season:</p>
1332c1336
< <li><p>Deletes yeoman <tt>JANICE_RAND</tt>
---
 > <li><p>Deletes yeoman <code>JANICE_RAND</code>
1335c1339
< <li><p>Adds <tt>PAVEL_CHEKOV</tt>
---
 > <li><p>Adds <code>PAVEL_CHEKOV</code>
1353c1357
< <li><p>Deleting <tt>JANICE_RAND</tt> is source incompatible, able to break
---
 > <li><p>Deleting <code>JANICE_RAND</code> is source incompatible, able 
to break
1358c1362
< methods on the enum, including <tt>values</tt> and <tt>valueOf</tt>.
---
 > methods on the enum, including <code>values</code> and 
<code>valueOf</code>.
1369c1373
< <li><p>Adding <tt>PAVEL_CHEKOV</tt> is binary-preserving source 
compatible.
---
 > <li><p>Adding <code>PAVEL_CHEKOV</code> is binary-preserving source 
compatible.
1393c1397
< <tt>compareTo</tt>.
---
 > <code>compareTo</code>.
1538c1542
< For this particular method, the specification also include information
---
 > For this particular method, the specification also includes information
1692,1693c1696,1697
< In particular, new JDK-internal interfaces should not expected to be
< usable from outside of the JDK.
---
 > In particular, new JDK-internal interfaces should <em>not</em> be
 > expected to be usable from outside of the JDK.
1871,1874c1875,1885
< platform specific code if you must.  Prefer writing solutions to
< problems in the JDK in the Java language compared to other languages,
< C, C++, shell, and so on; these preferences extend to writing
< regression tests.</p>
---
 > platform specific code if you must.
 >
 > Prefer writing solutions to problems in the JDK in the Java language
 > compared to other languages, C, C++, shell, and so on; these
 > preferences extend to writing regression tests.
 >
 > Note that for C and C++ code, the sources must compile successfully
 > under many different compilers, making cross-platform building and
 > testing especially important.
 >
 > </p>
1949,1950c1960,1961
< While revewing patch files is adaquate for small changes, larger
< changes are often facilated by use of <a
---
 > While reviewing patch files is adequate for small changes, larger
 > changes are often facilitated by use of <a
2013c2024
< Using a paired <code>@derepcated</code> javadoc tag for informative
---
 > Using a paired <code>@deprecated</code> javadoc tag for informative
2026a2038,2039
 > <li> Table of figures
 >
2030a2044
 > <li> Extra coding guidelines for C/C++ code