The OpenJDK Developers' Guide - DRAFT version 0.01

[Brad Wetmore]

Hi Iris,

Iris Clark wrote:

> I am pleased to announce that DRAFT version 0.01 of "The OpenJDK
> Developers' Guide" is now available at http://openjdk.java.net/guide.

Nice job culling down a lot of info.

> A
> mailing list, guide-discuss at openjdk.java.net, has been created for
> discussion.

Incidentally/personally, I tend to agree with folks regarding the 
overabundance of email aliases at Sun.  It's so easy to come to a 
project late, and you have no idea what aliases you *should* or 
*supposed* to be be on, meanwhile you're missing relevant discussions. 
Fortunately, they are archived.

Anyway, to specifics:

http://openjdk.java.net/guide/

I'd suggest putting an intro para here, just to say this is still under 
development, not complete, etc.  (or copying/moving that para from the 
intro page.)

http://openjdk.java.net/guide/intro.html

 > "Comments may be sent to..."

Suggest you also include a link to the guide-discuss archives:

http://mail.openjdk.java.net/pipermail/guide-discuss/

so people can see the back issues.

 > First, production of this document needs to be part of an OpenJDK
 > project.

Isn't the o.j.n hierarchy going to move to a mercurial repository soon? 
  If so, would that be a good place for it?  Or are you thinking of a 
separate repository just for this guide?

 > 2007/Q4

As it's now 2008/Q1, do you want to shift these dates by a quarter so 
people don't have unreasonable expectations?

http://openjdk.java.net/guide/repositories.html

 > "The JDK source is available from other locations, for example src.zip
 > from a full JDK distribution."

That is only partial source, so you should mention that in your later. 
Actually, I think you might want to open with the sentence "Portions of 
the JDK source are available..."

and

"OpenJDK contributions must use source from the OpenJDK Mercurial 
repositories..."

 > <h1> <h2> <h3>

This is probably outside your realm, but the current CSS style sheets 
don't really make an obvious distinction between the level header 
format.  I was hoping for at least a font size change to help me note 
the different parts of the hierarchy, not just an italics change.

 > The promoted builds are performed using the source in the MASTER
 > forest of repositories

The term MASTER was obvious when we had repositories called MASTER, but 
since they're now called jdk7, maybe you should add a note here showing 
where the MASTERS are for jdk7.

 > Repositories may be either read-only or read/write. Clones are made
 > from read-only repositories. Changeset pushes are made into the
 > read/write repositories, which are called gate repositories.

A picture's worth a thousand words.

      MASTER (R/O)<-------MASTER-gate (R/W)
        |                      ^
        |                      |
        +---->dev workspace----+

 > The repositories use following naming scheme:
 >
 >    <release>/<project>{-gate}?/<component>

Really suggest adding an example here:

     jdk7/JSN/jdk
     jdk7/TL-gate/langtools

 > Contact Mailing Lists

In addition to the mailto, maybe having a link to the archives?

 > build (also know as Release Engineering or RE)

also know*n* as.  Missing n.

 > hotspot-comp 	Hotspot Compiler implementation as provided by members
 > of the Hotspot group

I'm not parsing what this is supposed to be.  Does this mean 
hotspot-{comp,gc,rt,svc} all feed into this forest?

 > jsn   Security and Networking APIs and implementations as provided by

JSN does not include the original NIO, which are part of TL.  You might 
want to call this out.

 > Components
 >
 > The following table describes the components (or trees) in each forest
 > of repositories.

You should also mention the top level (previously known as control). 
Newbies might not appreciate that it is yet another repository.

 > http://www.selenic.com/mercurial/wiki/index.cgi.

Suggest using:  http://www.selenic.com/mercurial/wiki/

Also note, extra period at the end of the text that might be confusing 
to readers not using hyperlinks.  (i.e. those that print out this guide 
and enter the URL by hand.)  This will give a 404.

Same comment about the period for the other links:

     http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall.
     http://www.selenic.com/mercurial/wiki/index.cgi/ForestExtension.

 > Solaris:

We can talk about the following offline if you like, but working in 
mercurial under windows is *NOT* a straightforward process and should 
have a section of it's own.  You should talk about the windows gotchas, 
mainly that windows puts in ^M's at the end of lines, and they won't be 
allowed by jcheck.  (need to use dos2unix (solaris), flip (MKS), or 
something similiar (tr/sed/perl/etc))  Also, the default windows 
Mercurial distributions don't include a hgmerge file.  You have to 
create one.  And if it's a bourne shell merge script, it needs to be 
named hgmerge.sh, otherwise, it assumes a MSDOS script.

 > Create and edit the ~/.hgrc file to minimally contain the following
 > entries:

If you're going to be mentioning fetch here, you should probably add:

[defaults]
fetch = -m Merge

and also put in a mention for the eventual jcheck and its hooks.

 > jdk_username is a plain lowercase,

You need to have a section where you talk about how openjdk usernames 
are created/used, and then you need to link from here to there.

 > $ hg help
 > <a href=...>full output</a>

Either the abbreviated output should be moved here, or you need to say 
something like "<link to full output>"

 > Cloning...

Suggest reversing the order of single and forest.  Let them know there 
is a repository they can clone, then that forest can be used to simplify 
things...

Also, can they push to the sandbox?  We haven't really talked about 
pushes yet.

http://openjdk.java.net/guide/codeConventions.html

Suggest you at least mention the major expected changes such as whitespace.

http://openjdk.java.net/guide/changePlanning.html

 > are urged to work with their sponsors

Iris wrote:

 > I don't think we've yet defined what the
 > protocol should be for working with your sponsor.

Since sponsors haven't been defined yet, you should probably at least 
have a link to http://openjdk.java.net/contribute/

 > CCC/SDN/jdcinclude/etc.

Looks like Andy Tripp had the same comment.

Lots of these terms have not been described yet, so it's not clear 
what's involved.  Yes, these sections are TBD, but you might want to at 
least give a 2 second description here so people aren't scratching their 
heads as to what CCC is/does, or else fill in that part in the glossary now.

 > I'm not quite sure what "CCC" stands for

I've heard Committee of Concerned Citizens, Change Consideration 
Committee, and the Committee of Cranky Curmudgeons.  Ok, I made that 
last one up...  ;)

 > For bugs, provide a jtreg regression test

Provide a link to jtreg.

 > -hard

You should say that you should at least try to come up with a race case, 
not just simply use noreg-hard because you're not sure if it can be 
dup'd.  I've written several relatively easy race cases that were 
originally marked noreg-hard.

 > 10. Run relevant regression and unit tests on all relevant platforms

to which Lars Westergren wrote:

 > Until there is a more complete page in place, perhaps you could just
 > add the following to the page for those who are currently working on
 > patches-
 >
 > "OpenJDK tests are located in the jdk/test directory. If for instance
 > you have been changing code in the management package, you should at
 > the minimum run the tests located in jdk/test/java/lang/management"

and Jon wrote:

 > Note that not all the tests are in jdk/test.  There are also tests in
 > langtools/test.

and hotspot/test.

I strongly suggest adding a note here to check with your gatekeeper 
and/or project group to determine which tests to run.

http://openjdk.java.net/guide/producingChangeset.html

 > Setting a JDK User Name

Same comment about how to obtain an OpenJDK User name.

You might want to point a bit earlier to "Installing and Configuring 
Mercurial" instead of "Verifying the Configuration", so in case the 
users haven't already set their username, they will know how and what it 
should look like when properly configured.

 > ...

Nowhere is jcheck mentioned here.  It needs to be clear that there will 
be restrictions on content in both the changeset description and the 
files themselves, and that jcheck will be enforcing that at both the 
local and repository level.  It's fine to say "jcheck is under development."

 > The timing for creating a changeset is important.

I'd suggest simply advising that changesets should only be created after 
review, and just before checkin.  With the way jcheck is currently set 
to operate, you can only use a bugid once in a repository.  Any changes 
either have to be backed out completely before an integration, or else a 
new bugid has to be created.

 > They are therefore identified by their OpenJDK usernames rather than
 > full e-mail addresses.

This is an aside, but how do we figure out the username->user->email 
mapping?

 > If a changeset contains multiple unrelated changes (this is frowned
 > upon, but may happen from time to time) then its comment will contain
 > multiple blocks of the above form, separated by blank lines.

Blank lines are not allowed anywhere in a changeset comment, at least in 
Mark's current jcheck.

 > The required format of the comments will be enforced whenever the
 > changeset is pushed into the JDK 6/7

This is the only place you mention JDK 6/7 by name.  Since OpenJDK6 is 
still under teamware for a while longer, maybe you want to keep this 
generic to OpenJDK?

 > Option 1: hg fpull

I'd suggest "hg fpull; hg fupdate"

 > At this point, there are no recommendations for the format of the
 > merge comment.

Currently it's "Merge" in jcheck.

 > Actual file merging will be done with the selected Mercurial merging
 > tool see MergeProgram for the details on how to define the selected
 > merge tool in ~/.hgrc.

Shouldn't we get into silent/automatic/fuzzy merges here?

 > For MASTER repositories, the integrators and members of the Release
 > Engineering Team can push.

I think the term "gatekeepers" should be used here instead of 
"integrators".  IMHO, integrators is too generic a term, and means 
anyone who integrates code into a repository, and can be hard to explain 
to outside folks.  A gatekeeper, by contrast, is a different type of 
person who controls access to the MASTERs.

I would also suggest adding a note somewhere about how code goes from 
the project gates to the MASTERs.   (i.e. gatekeepers).  If you haven't 
seen it already:

     http://blogs.sun.com/wetmore/entry/you_re_a_gatekeeper_uh

http://openjdk.java.net/guide/glossary.html

I'd suggest pulling in parts of Kelly's Glossary here.

http://wikis.sun.com/display/OpenJdkBuilds/JDK+Glossary+of+Terms

HTH,

Brad