some thoughts about Change Planning page

[iris clark]

Hi, Andy.

> I just found this guide - great idea!

Thanks for the review comments.  

> Here are some thoughts I had on this page: 
> http://openjdk.java.net/guide/changePlanning.html
> 
> * step 2, creating a bug, should go first

I was optimizing for a different case, namely that most problems that
have been reported turn out to be duplicates of existing bugs. 
Sometimes the fact that it's a duplicate doesn't become apparent until
after discussion.  This is particularly true for new features which
may overlap work currently planned or in progress.

The order in the Guide also describes the current process, but I don't
consider this part of the sequence rigid.  Submitting a bug first
would allow for better tracking.  We may consider changing this order
if others provide similar feedback or if we determine that tracking of
the initial discussions is difficult.

> * you mention "work with their sponsors" without saying what that means.

Yes, this is a hole.  I don't think we've yet defined what the
protocol should be for working with your sponsor.  We all imagine it
to be a fairly informal interaction but we don't yet know if it will
be more common for the contributor to drive the change or the sponsor.
For instance, is the contributor require to detail the changes which
need to be applied to the bug when they need to occur or is that left
to the discretion of the sponsor?  Do we even want to define this?

> * you mention a "CCC" without saying what it is. What does the acronym 
> stand for and
>  give me a link to find out more.

I'm not quite sure what "CCC" stands for (and I'm on it :) ).  In the
back of my mind, I think it stands for "Committee for Concerned
Citizens", but that could have been a punchline for a joke.

Nevertheless, the CCC is ann important part of our current process.
It is responsible for auditing anything that would change spec or
externally visible behaviour in the JDK, such as adding a new API,
tool option, or system property.

The CCC is one of the "Process Tools" for interface review and change
approval that Mark references in this blog:

  Upcoming OpenJDK infrastructure projects
  http://blogs.sun.com/mr/entry/under_construction

I'll provide a definition of CCC and reference it in the Guide as
appropriate.  We'll need to keep in mind that the this review body's
function (and possibly name) will likely change as as externalize its
function.  For this reason, we've been reluctant to provide much
documentation about it.

> * you mention "jtreg regression test" also. describe it and give a link.

Good idea.  
 
> * in step 6 answer "N", an explanation is required *where*? in some 
> field of the entry
>  in the bug database?

Historically we've advised that this information be added to the
"Comments" section of the bug; however, since that's not a visible
field, this should probably be revised to define some other
publically-visible field.  Off the top of my head, the "Evaluation"
section sounds appropriate.  I'll update this sentence to explicitly
mention a section.

> * why does step 8 require testing on just one OS, but step 9 on all? 

Here's the text for Step 8, "yes":

  Build and test on at least one instance of all three of the supported
  operating systems (Solaris, Linux, and Windows).

Here's the text for Step 9, "yes":

  Build and test on all relevant platforms. Code under src/solaris
  builds on both Solaris and Linux, despite its name.

I don't see an inconsistency here.  Step 8 requires testing on at
least three platforms.  This has been a requirement for years.  All of
our build platforms are treated equally when group integrations occur,
so if a change is supposed to apply to all platforms and a test
reveals that it fails on one of them, then there's a general problem
with the change which needs to be addressed.  

> And 
> do you really
>   require that every change be tested on every platform by the developer 
> making the change?
>  That doesn't seem feasible.

We expect the person making the change to have some understanding of
the potential risks of not testing everywhere.  For example,
historically we have discovered that changes in the launcher really
need to be tested on all of the supported platforms because failure to
do so will introduce severe regressions.  If you fail to do sufficient
testing, you run the risk of breaking the build which can be extremely
disruptive.

We understand that many contributors don't have ready access to 
build/test machines on all the supported platforms.  One of the
sponsor's reponsibilities is to ensure that the appropriate tests have
been run.  The sponsor does have access to machines for all of the
build platforms and can assist contributors in validating their
changes.  This can be a heavy burden on sponsors, but until we provide
a distributed build/test system (as described in Mark's blog), we have
no other choice.  Note that some groups, such as the Hotspot Team are
very strict about comprehensive platform testing and have a system to
require testing on all changes as part of the commit process.  Changes
which are committed but fail testing on any platform will never make
it into one of their repositories.

I think this all comes back to the fact that sponsorship has not been
defined.  

Thanks,
iris