Hi David,

On 4/3/06, David W. Van Couvering <David.Vancouvering@sun.com> wrote:


Satheesh Bandaram wrote:
> This is a very good list... Thanks for putting this together. Should we
> consider documenting some of the important items once the Wiki page is
> more firmed up?
>

Are you saying some of these interfaces, while supported, are not
documented?  See Jeff Levitt's comment, I would argue that anything
undocumented must be marked as a Private interface until documented.

No, I meant to ask if the table of Derby interfaces and their stability levels that you are cooking up should be documented? Instead of documenting the whole table, I was asking may be we could identify important interfaces and their stability levels.

> Some more items to include:
>
> 1) Trace outputs. Many modules have tracing support. Should this be
> marked PRIVATE?

Yes, I can add that.

> 2) Errorlog contents. UNSTABLE?

I had derby.log format, isn't that the same thing?

Yes... It is. I missed it in the list.

> 3) Query plan output as displayed by RUNTIMESTATISTICS. UNSTABLE?

If it's documented, Unstable seems good.  If it's not documented, then
we should mark it as Private.

We do document output of RUNTIMESTATISTICS and how to analyse it in Tuning guide.

> 4) Derby properties. I think Documented properties should be marked
> STABLE. Undocumented properties are UNSTABLE.

Undocumented properties should probably be marked Private, by their very
nature they can't be Unstable since they're not documented.

Guess PRIVATE is better for undocumented properties. You are right...

Satheesh

David

>
> Satheesh
>
> On 3/31/06, *David W. Van Couvering* <David.Vancouvering@sun.com
> <mailto: David.Vancouvering@sun.com>> wrote:
>
>     I've updated the Wiki page to reflect some of this discussion and my
>     sense of where things are ending up.  You can use the diff mechanism of
>     the Wiki to see what's changed.
>
>     David
>
>     Kathey Marsden wrote:
>      > Rick Hillegas wrote:
>      >
>      >
>      >>I think you may have already addressed the following issues in email,
>      >>but I don't see the results rolled onto the wiki page. Please pardon
>      >>my nitpicking. This kind of discussion turns me into a tiresome,
>      >>pedantic Mr. Hyde:
>      >>
>      >>1) The cardinal rule. I recommend wordsmithing the cardinal rule:
>     "The
>      >>goal is to allow any application written against the public
>     interfaces
>      >>an older version of Derby can run, without any changes, against a
>      >>newer version of Derby." To me the following formulation reads better
>      >>"This is our goal: An application which ran against Derby yesterday
>      >>will run against a higher version of Derby tomorrow."
>      >>
>      >
>      > I prefer the original wording with only a small grammatical change to
>      > instead of can.
>      >
>      > "The goal is to allow any application written against the public
>      > interfaces an older version of Derby to run, without any changes,
>      > against a newer version of Derby."
>      >
>      > It is good to think past tomorrow.
>      >
>      >
>      >>But is that really the cardinal rule? Maybe we really mean this:
>     "This
>      >>is our goal: An application which runs against a Derby release today
>      >>will also run tomorrow against the next minor release.
>      >
>      >
>      > I  do not like this wording .    It might seem to imply that you
>     cannot
>      > skip minor releases e.g. go from 10.l  to 10.3.
>      > It might also seem to imply that you cannot  run a 10.1 client with a
>      > 10.3 server for example.
>      >
>      >
>      >>We strive to minimize churn for applications migrating to the next
>      >>major release of Derby. However these migrations may entail
>      >>application changes."
>      >>
>      >
>      > The way  major releases are described in this mail is the way I have
>      > seen them  in the past,  where we break upgrade,  client/server
>      > compatibility and many other things  and it is like switching to
>     a new
>      > product, but I want better for the users of  Derby 10 when they
>     switch
>      > to 11.
>      >
>      > I still need to think a lot about the whole major version boundary
>      > thing.  It seems like we like solaris will be set at the same major
>      > version for a very long time.   As I stated before I think for some
>      > things a time based approach seems most appropriate. You can
>     expect your
>      > client to work with new servers for the next five years for
>     example. We
>      > should  not just leave users trying to figure out how to
>     upgrade  their
>      > server and all of their clients all in one night because
>     we  bumped from
>      > 10 to 11.
>      >
>      > If we expect upgrade=true to work from 10 to 11 we should expect
>      > client/server compatibility to be maintained as well.
>      > So either the time based approach or for major versions  have
>      > compatibility with the previous and next  major versions.    For
>     example
>      > with Derby 11 you can use Derby 10 or Derby 12, but not Derby 13.
>      >
>      >
>      >>2b) Our DRDA implementation may incorrectly transport datatypes not
>      >>recognized by DRDA. Conforming to the DRDA spec may mean removing
>     this
>      >>transport capability and breaking applications which select the
>      >>unsupported datatypes.
>      >>
>      >
>      > Protocol has an impact on client JDBC, SQL  and even the ability to
>      > connect and those cannot be broken.
>      > Client and server can have version dependent behaviour to
>     mitigate the
>      > change to DRDA compliant behavior.
>      >
>      >
>      >
>      >>3) Client/server compatibility.
>      >>
>      >>I would expect to find these rules spelled out on the wiki page.
>      >
>      >
>      >
>      >
>      > Yes I agree these should be spelled out because obviously different
>      > readers can deduce different things.
>      >
>      >
>      >
>
>