You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "David W. Van Couvering" <Da...@Sun.COM> on 2006/03/29 01:39:52 UTC
Discussion (in preparation for a vote) on interface stability table
Hi, all. I would like to propose that we have a discussion, in
preparation for (at some time in the future) a vote on the interface
table I put together at
http://wiki.apache.org/db-derby/ForwardCompatibility
The approach I was thinking of is:
- everybody who is interested take a look at this table, and raise
issues as needed
- discussion ensues as needed
- I will incrementally update the Wiki page when it seems there is a
consensus on a particular issue
Once things have somewhat stabilized (and where there is contention,
people are starting to repeat themselves :)), I'll then I'll hold a
vote. The vote email will contain the relevant text and the interface
table from the Wiki page, so that we know what we're voting on and so
that it ends up in the archives.
This interface table would be for the next release of Derby (10.1.3 or
10.2, whichever comes first).
I would like to suggest that if you want to discuss the stability
classification of a *particular* interface, you do so with a separate,
specific email subject line, so that those who may be interested will
notice and participate.
How does this sound?
Does anyone think we need to vote on the interface taxonomy and the
definition of an interface separate from the stability classifications
given to each interface?
David
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Satheesh Bandaram <sa...@Sourcery.Org>.
David W. Van Couvering wrote:
>
> If we want to also provide a guarantee that any feature will not be
> broken for five years, that's OK, but I think it would be odd to break
> compatibility in a minor release just because it's been five years...
>
> Or am I not fully understanding your proposal, Kathey?
>
I think Kathey probably meant compatibility should be maintained for a
specific amount of time AND can only be broken in a major release.
Satheesh
> 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.
>>
>>
>>
>
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I'll let you go ponder, but I guess I don't fully understand. It is a
Bad Thing at any time to break client/server compatibility. Hopefully
we never have to do it. I guess my only point, and I think the point of
this Wiki, is that *when* we have to do it, we have to do it at a major
release boundary, and we will document clearly that there is an
incompatibility.
If we can make a change such that it only breaks compatibility with
major release - 2 (e.g. the change in 12.0 works with 11.x clients but
not with 10.x clients), that's great. We can even agree to make this a
policy. But to me that doesn't meant we can make the change at a minor
release boundary.
David
Kathey Marsden wrote:
> David W. Van Couvering wrote:
>
>
>>I also wanted to respond to the suggestion that compatibility be
>>guaranteed for a given time period, versus tying it to release levels.
>>
>>If we don't *require* that major releases be incompatible, but simply
>>say this is the only time you *can* do it, then I don't see what the
>>issue is. We can do as many major releases as we want in five years.
>>
>>If we want to also provide a guarantee that any feature will not be
>>broken for five years, that's OK, but I think it would be odd to break
>>compatibility in a minor release just because it's been five years...
>>
>>Or am I not fully understanding your proposal, Kathey?
>
>
> It is not a proposal, kind of more of a typical user requirement. I
> need to think some more on how to that might be implemented from a
> product perspective. Perhaps the guarantee of client/server
> compatibility with the previous and next major release would be a
> more realistic approach. Certainly the kind of jump suggested where
> there is no compatibility between v10 and v11 clients and servers would
> be a very hard move for users. Upgrade is another area I need to
> understand better across major version boundaries. Anyway, all just
> random thoughts at this point. As I said I need to think more. I will
> study your proposal and all this just as soon as I can and get back.
>
> Kathey
>
>
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Kathey Marsden <km...@sbcglobal.net>.
David W. Van Couvering wrote:
> I also wanted to respond to the suggestion that compatibility be
> guaranteed for a given time period, versus tying it to release levels.
>
> If we don't *require* that major releases be incompatible, but simply
> say this is the only time you *can* do it, then I don't see what the
> issue is. We can do as many major releases as we want in five years.
>
> If we want to also provide a guarantee that any feature will not be
> broken for five years, that's OK, but I think it would be odd to break
> compatibility in a minor release just because it's been five years...
>
> Or am I not fully understanding your proposal, Kathey?
It is not a proposal, kind of more of a typical user requirement. I
need to think some more on how to that might be implemented from a
product perspective. Perhaps the guarantee of client/server
compatibility with the previous and next major release would be a
more realistic approach. Certainly the kind of jump suggested where
there is no compatibility between v10 and v11 clients and servers would
be a very hard move for users. Upgrade is another area I need to
understand better across major version boundaries. Anyway, all just
random thoughts at this point. As I said I need to think more. I will
study your proposal and all this just as soon as I can and get back.
Kathey
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I also wanted to respond to the suggestion that compatibility be
guaranteed for a given time period, versus tying it to release levels.
If we don't *require* that major releases be incompatible, but simply
say this is the only time you *can* do it, then I don't see what the
issue is. We can do as many major releases as we want in five years.
If we want to also provide a guarantee that any feature will not be
broken for five years, that's OK, but I think it would be odd to break
compatibility in a minor release just because it's been five years...
Or am I not fully understanding your proposal, Kathey?
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.
>
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by Rick Hillegas <Ri...@Sun.COM>.
Kathey Marsden wrote:
>
>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.
>
>
This is quite puzzling. I've never worked for an engineering operation
which could make this five-year guarantee. Personally, I don't know
anyone who has this kind of foresight. Five years is the classic
lifetime of a complex product before it needs an incompatible
overhaul/rewrite. What happens to the clients released in the last year
of that usable lifetime? Please provide more detail here.
Thanks,
-Rick
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I think we should clarify the page, then. My intent was not that a
major release *will* be incompatible. My intent was that a major
release *might* be incompatible, whereas minor releases can *not* be
incompatible.
David
Daniel John Debrunner wrote:
> 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.
>
>
> +1
>
> The push towards allowing a major release to change things worries me.
> It may be that we need to do this from time to time, but it should not
> be the primary goal.
> Dan.
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Daniel John Debrunner <dj...@apache.org>.
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.
+1
The push towards allowing a major release to change things worries me.
It may be that we need to do this from time to time, but it should not
be the primary goal.
Dan.
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Hi, John, thanks for reviewing this.
I agree "Private Unstable" sounds more unstable than "Private." I don't
know if we need "Private Unstable" and I can remove it. Alternately, we
could rename "Private" to "Private Volatile" :)
I'll get rid of Private Unstable for now since we don't have any
interfaces that meet that requirement, and may never. We can always add
it in later.
David
John Embretsen wrote:
> Friday, March 31, 2006, 9:34:30 PM CET, David W. Van Couvering 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.
>
>
> I was trying to understand all the different stability levels you
> suggested on http://wiki.apache.org/db-derby/ForwardCompatibility, and
> have one question:
>
> Do we really have to differentiate between between a "Private" and a
> "Private Unstable" interface?
>
> If so, can you also explain to me why you are saying that "Private"
> interfaces allow incompatible change at any time, while "Private
> Unstable" only allows such changes at minor release? To me the term
> "Private Unstable" certainly sounds less stable than "Private"...
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by John Embretsen <Jo...@Sun.COM>.
Friday, March 31, 2006, 9:34:30 PM CET, David W. Van Couvering 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.
I was trying to understand all the different stability levels you
suggested on http://wiki.apache.org/db-derby/ForwardCompatibility, and
have one question:
Do we really have to differentiate between between a "Private" and a
"Private Unstable" interface?
If so, can you also explain to me why you are saying that "Private"
interfaces allow incompatible change at any time, while "Private
Unstable" only allows such changes at minor release? To me the term
"Private Unstable" certainly sounds less stable than "Private"...
--
John
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I think it might be good to document these as part of the release notes
or release documentation. I don't have strong feelings about this, but
it seems like a good idea.
David
Satheesh Bandaram wrote:
> Hi David,
>
> On 4/3/06, *David W. Van Couvering* <David.Vancouvering@sun.com
> <ma...@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
> <ma...@sun.com>
> > <mailto: David.Vancouvering@sun.com
> <ma...@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.
> > >
> > >
> > >
> >
> >
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Satheesh Bandaram <ba...@gmail.com>.
Hi David,
On 4/3/06, David W. Van Couvering <Da...@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
> > <ma...@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.
> > >
> > >
> > >
> >
> >
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
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.
> 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?
> 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.
> 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.
David
>
> Satheesh
>
> On 3/31/06, *David W. Van Couvering* <David.Vancouvering@sun.com
> <ma...@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.
> >
> >
> >
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Satheesh Bandaram <ba...@gmail.com>.
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?
Some more items to include:
1) Trace outputs. Many modules have tracing support. Should this be marked
PRIVATE?
2) Errorlog contents. UNSTABLE?
3) Query plan output as displayed by RUNTIMESTATISTICS. UNSTABLE?
4) Derby properties. I think Documented properties should be marked STABLE.
Undocumented properties are UNSTABLE.
Satheesh
On 3/31/06, David W. Van Couvering <Da...@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.
> >
> >
> >
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
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.
>
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Kathey Marsden <km...@sbcglobal.net>.
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.
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I don't know the specific bug and the impact. My intuition says
document the change. But if it were a significant enough change, I
might consider providing support for the old, broken behavior. I hope
that this is a discussion that can be had around this bug by the
contributor and his/her reviewers.
David
Rick Hillegas wrote:
> We already have to cross this bridge for the next release of Derby.
> DERBY-280 is a correctness bug, which while not fixed, was patched. This
> changes the behavior of a family of queries which were returning wrong
> results. What should we do:
>
> 1) Add and document a tracepoint allowing customers to get the previous
> incorrect behavior? Please say no. I think we all believe this is a
> crummy solution.
> 2) Document the changed behavior in the Release Notes. If an important
> customer complains, then we can evaluate how to satisfy that customer in
> a follow-on release.
> 3) Something else?
>
> -Rick
>
> David W. Van Couvering wrote:
>
>> I agree this sounds like a terrible model. But we have to accept
>> reality, we *are* going to have bugs. And if we can't fix those bugs
>> in a backward-compatible way, then it is more than likely that some
>> Big Huge Customer will refuse to upgrade. I saw that at Sybase as
>> well. Perhaps the cost of supporting older codelines is ultimately a
>> better choice for our product than the spaghetti of micro-compatbility
>> if-statements and weird "behavior plugins" in the code.
>>
>> I don't have an easy answer. I agree we should strive for
>> correctness, and perhaps we'll just have to cross that bridge when we
>> come to it. I think Rick's caveats are valuable, but I don't want
>> them to be a loophole that we then use to feel we have more free rein
>> to break compatibility. But, saying that, knowing this lot I suspect
>> we don't have to worry about this, you can't sneeze around here
>> without someone worrying whether than sneeze was compatible with your
>> last sneeze :)
>>
>> David
>>
>> Daniel John Debrunner wrote:
>>
>>> Rick Hillegas wrote:
>>>
>>>
>>>> Thanks, David. I think this discussion is raising some interesting
>>>> issues.
>>>>
>>>> David W. Van Couvering wrote:
>>>>
>>>>
>>>>>> 2) Bug fixing policy.
>>>>>>
>>>
>>>
>>>> I am glad that we are bothering to make these rules explicit. In a
>>>> previous life at Sybase, we solved this problem by adding special
>>>> tracepoints for big, important customers who relied on old, incorrect
>>>> behavior. As I recall, we didn't know up front who would object to a
>>>> correction. The tracepoints went into patch releases based on customer
>>>> dissatisfaction with the last minor release.
>>>>
>>>> Do you think the Sybase model will work for us? Or do we need to add
>>>> tracepoints to the minor release as we fix the incorrect behavior?
>>>> Maybe
>>>> it is not good enough to add a master tracepoint with the semantics
>>>> "Simulate all incorrect implementations of the standards fixed in this
>>>> release, X.y." Customers may want something more granular, say, a
>>>> tracepoint per obnoxious correction. Over time, these tracepoints will
>>>> pile up and the code will become a more exciting pinball machine. What
>>>> are your thoughts?
>>>
>>>
>>>
>>>
>>> I think it's a terrible model. This moves the project into a state where
>>> the number of possible execution time modes will increase rapidly,
>>> causing nightmares for those who have to support it or answer questions
>>> on the user list.
>>>
>>> For any change we as a community should be confident it is the correct
>>> change.
>>>
>>> [disclaimer - I was at Sybase during those times ]
>>>
>>> Dan.
>>>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I think this is a good approach. Having the project open source solves
some of these nasty "bug-compatibility" issues that can occur with
closed-source projects with Big Customers.
I'll try to add something to this effect in the Wiki page, although it
may already be covered in the Exceptions section.
David
Oystein Grovlen - Sun Norway wrote:
> Daniel John Debrunner wrote:
>
>> Remember this is open-source, there are no customers or "important
>> customers", only users and developers.
>>
>> If a user doesn't like the solution they have at least two options:
>>
>> - get involved in the Derby developer community
>> - patch the source
>>
>> I prefer the first.
>
>
> Good point, Dan.
>
> Users of Derby has several options when a new release break their
> application:
> - Fix their application
> - Use the old release (i.e., not upgrade)
> - Pay someone (e.g. Sun or IBM) to fix their problem.
> - Get involved in the Derby community and suggest a fix to their
> problem.
> - Patch the source by reverting the fix that causes problem for them.
>
> I am pretty sure that there will case where it is NOT worth the extra
> effort by the community to ensure that a specific user is able to upgrade.
>
> I also think it is a violation of the Derby charter to NOT fix bugs or
> correct sql-states for compatibility reasons. The Derby charter states
> that Derby is standard compliant. If there are cases where it does not
> comply to the standard, we have the obligation to fix that.
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by Oystein Grovlen - Sun Norway <Oy...@Sun.COM>.
Daniel John Debrunner wrote:
> Remember this is open-source, there are no customers or "important
> customers", only users and developers.
>
> If a user doesn't like the solution they have at least two options:
>
> - get involved in the Derby developer community
> - patch the source
>
> I prefer the first.
Good point, Dan.
Users of Derby has several options when a new release break their
application:
- Fix their application
- Use the old release (i.e., not upgrade)
- Pay someone (e.g. Sun or IBM) to fix their problem.
- Get involved in the Derby community and suggest a fix to their
problem.
- Patch the source by reverting the fix that causes problem for them.
I am pretty sure that there will case where it is NOT worth the extra
effort by the community to ensure that a specific user is able to upgrade.
I also think it is a violation of the Derby charter to NOT fix bugs or
correct sql-states for compatibility reasons. The Derby charter states
that Derby is standard compliant. If there are cases where it does not
comply to the standard, we have the obligation to fix that.
--
?ystein Gr?vlen, Senior Staff Engineer
Sun Microsystems, Database Technology Group
Trondheim, Norway
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Daniel John Debrunner <dj...@apache.org>.
Rick Hillegas wrote:
> We already have to cross this bridge for the next release of Derby.
> DERBY-280 is a correctness bug, which while not fixed, was patched. This
> changes the behavior of a family of queries which were returning wrong
> results. What should we do:
>
> 2) Document the changed behavior in the Release Notes. If an important
> customer complains, then we can evaluate how to satisfy that customer in
> a follow-on release.
Remember this is open-source, there are no customers or "important
customers", only users and developers.
If a user doesn't like the solution they have at least two options:
- get involved in the Derby developer community
- patch the source
I prefer the first.
Dan.
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by Rick Hillegas <Ri...@Sun.COM>.
We already have to cross this bridge for the next release of Derby.
DERBY-280 is a correctness bug, which while not fixed, was patched. This
changes the behavior of a family of queries which were returning wrong
results. What should we do:
1) Add and document a tracepoint allowing customers to get the previous
incorrect behavior? Please say no. I think we all believe this is a
crummy solution.
2) Document the changed behavior in the Release Notes. If an important
customer complains, then we can evaluate how to satisfy that customer in
a follow-on release.
3) Something else?
-Rick
David W. Van Couvering wrote:
> I agree this sounds like a terrible model. But we have to accept
> reality, we *are* going to have bugs. And if we can't fix those bugs
> in a backward-compatible way, then it is more than likely that some
> Big Huge Customer will refuse to upgrade. I saw that at Sybase as
> well. Perhaps the cost of supporting older codelines is ultimately a
> better choice for our product than the spaghetti of micro-compatbility
> if-statements and weird "behavior plugins" in the code.
>
> I don't have an easy answer. I agree we should strive for
> correctness, and perhaps we'll just have to cross that bridge when we
> come to it. I think Rick's caveats are valuable, but I don't want
> them to be a loophole that we then use to feel we have more free rein
> to break compatibility. But, saying that, knowing this lot I suspect
> we don't have to worry about this, you can't sneeze around here
> without someone worrying whether than sneeze was compatible with your
> last sneeze :)
>
> David
>
> Daniel John Debrunner wrote:
>
>> Rick Hillegas wrote:
>>
>>
>>> Thanks, David. I think this discussion is raising some interesting
>>> issues.
>>>
>>> David W. Van Couvering wrote:
>>>
>>>
>>>>> 2) Bug fixing policy.
>>>>>
>>
>>
>>> I am glad that we are bothering to make these rules explicit. In a
>>> previous life at Sybase, we solved this problem by adding special
>>> tracepoints for big, important customers who relied on old, incorrect
>>> behavior. As I recall, we didn't know up front who would object to a
>>> correction. The tracepoints went into patch releases based on customer
>>> dissatisfaction with the last minor release.
>>>
>>> Do you think the Sybase model will work for us? Or do we need to add
>>> tracepoints to the minor release as we fix the incorrect behavior?
>>> Maybe
>>> it is not good enough to add a master tracepoint with the semantics
>>> "Simulate all incorrect implementations of the standards fixed in this
>>> release, X.y." Customers may want something more granular, say, a
>>> tracepoint per obnoxious correction. Over time, these tracepoints will
>>> pile up and the code will become a more exciting pinball machine. What
>>> are your thoughts?
>>
>>
>>
>> I think it's a terrible model. This moves the project into a state where
>> the number of possible execution time modes will increase rapidly,
>> causing nightmares for those who have to support it or answer questions
>> on the user list.
>>
>> For any change we as a community should be confident it is the correct
>> change.
>>
>> [disclaimer - I was at Sybase during those times ]
>>
>> Dan.
>>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I agree this sounds like a terrible model. But we have to accept
reality, we *are* going to have bugs. And if we can't fix those bugs in
a backward-compatible way, then it is more than likely that some Big
Huge Customer will refuse to upgrade. I saw that at Sybase as well.
Perhaps the cost of supporting older codelines is ultimately a better
choice for our product than the spaghetti of micro-compatbility
if-statements and weird "behavior plugins" in the code.
I don't have an easy answer. I agree we should strive for correctness,
and perhaps we'll just have to cross that bridge when we come to it. I
think Rick's caveats are valuable, but I don't want them to be a
loophole that we then use to feel we have more free rein to break
compatibility. But, saying that, knowing this lot I suspect we don't
have to worry about this, you can't sneeze around here without someone
worrying whether than sneeze was compatible with your last sneeze :)
David
Daniel John Debrunner wrote:
> Rick Hillegas wrote:
>
>
>>Thanks, David. I think this discussion is raising some interesting issues.
>>
>>David W. Van Couvering wrote:
>>
>>
>>>>2) Bug fixing policy.
>>>>
>
>
>>I am glad that we are bothering to make these rules explicit. In a
>>previous life at Sybase, we solved this problem by adding special
>>tracepoints for big, important customers who relied on old, incorrect
>>behavior. As I recall, we didn't know up front who would object to a
>>correction. The tracepoints went into patch releases based on customer
>>dissatisfaction with the last minor release.
>>
>>Do you think the Sybase model will work for us? Or do we need to add
>>tracepoints to the minor release as we fix the incorrect behavior? Maybe
>>it is not good enough to add a master tracepoint with the semantics
>>"Simulate all incorrect implementations of the standards fixed in this
>>release, X.y." Customers may want something more granular, say, a
>>tracepoint per obnoxious correction. Over time, these tracepoints will
>>pile up and the code will become a more exciting pinball machine. What
>>are your thoughts?
>
>
> I think it's a terrible model. This moves the project into a state where
> the number of possible execution time modes will increase rapidly,
> causing nightmares for those who have to support it or answer questions
> on the user list.
>
> For any change we as a community should be confident it is the correct
> change.
>
> [disclaimer - I was at Sybase during those times ]
>
> Dan.
>
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Daniel John Debrunner <dj...@apache.org>.
Rick Hillegas wrote:
> Thanks, David. I think this discussion is raising some interesting issues.
>
> David W. Van Couvering wrote:
>
>>
>>>
>>> 2) Bug fixing policy.
>>>
> I am glad that we are bothering to make these rules explicit. In a
> previous life at Sybase, we solved this problem by adding special
> tracepoints for big, important customers who relied on old, incorrect
> behavior. As I recall, we didn't know up front who would object to a
> correction. The tracepoints went into patch releases based on customer
> dissatisfaction with the last minor release.
>
> Do you think the Sybase model will work for us? Or do we need to add
> tracepoints to the minor release as we fix the incorrect behavior? Maybe
> it is not good enough to add a master tracepoint with the semantics
> "Simulate all incorrect implementations of the standards fixed in this
> release, X.y." Customers may want something more granular, say, a
> tracepoint per obnoxious correction. Over time, these tracepoints will
> pile up and the code will become a more exciting pinball machine. What
> are your thoughts?
I think it's a terrible model. This moves the project into a state where
the number of possible execution time modes will increase rapidly,
causing nightmares for those who have to support it or answer questions
on the user list.
For any change we as a community should be confident it is the correct
change.
[disclaimer - I was at Sybase during those times ]
Dan.
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by Rick Hillegas <Ri...@Sun.COM>.
Thanks, David. I think this discussion is raising some interesting issues.
David W. Van Couvering wrote:
>
>>
>> 2) Bug fixing policy.
>>
>> I think that the Exceptions section should say explicitly that "It is
>> OK for minor releases to fix bugs in our implementation of the
>> standards, even if those fixes break existing applications."
>> Bugfixes can and do break applications and so violate the cardinal
>> rule. Here are some more examples:
>>
>> 2a) Wrong query results. The correct results may break applications
>> which are either unaware of the problem or which have already written
>> compensatory logic to patch over our error. Correct results may slow
>> down the query's performance and the customer may consider this
>> degradation intolerable.
>>
>
> Ooh. I can tell you speak from experience. I would actually argue
> that this is not acceptable. You can't just break applications
> without warning. What I have seen in the past is you provide the user
> to enable the old or new behavior through some kind of flag, e.g.
> derby.use.old.broken.behavior or derby.use.new.fixed.behavior
I am glad that we are bothering to make these rules explicit. In a
previous life at Sybase, we solved this problem by adding special
tracepoints for big, important customers who relied on old, incorrect
behavior. As I recall, we didn't know up front who would object to a
correction. The tracepoints went into patch releases based on customer
dissatisfaction with the last minor release.
Do you think the Sybase model will work for us? Or do we need to add
tracepoints to the minor release as we fix the incorrect behavior? Maybe
it is not good enough to add a master tracepoint with the semantics
"Simulate all incorrect implementations of the standards fixed in this
release, X.y." Customers may want something more granular, say, a
tracepoint per obnoxious correction. Over time, these tracepoints will
pile up and the code will become a more exciting pinball machine. What
are your thoughts?
>
>> 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.
>>
>
> I think it would be unacceptable to remove unsupported datatypes, even
> if they are not spec compliant. Again, you use versioning and
> capabilities negotiation to change in a compatible way. For example,
> if someone has an itch to support a network client that can only
> handle the types specified in DRDA, and the network client today
> supports non-standard types, then we should provide an option to run
> in "standard-DRDA" mode and disable those types.
>
> If we want to add new, non-standard types, then we should only support
> these types if the client explicitly says it can handle them.
I'm happy with this approach. I would like to see the wiki state these
rules explicitly.
>
>
>>
>> 3) Client/server compatibility.
>>
>> I would expect to find these rules spelled out on the wiki page. It
>> is not clear to me that you can deduce client/server compatibility
>> from the cardinal rule. Are these the rules?
>
>
> I did add a note based on Kathey's comments. I think you *can*
> achieve this by declaring the right interfaces as Stable or Private
> Stable, but I agree it's good to call it out.
Thanks.
>
>>
>> 3a) A major release number defines a family of compatible Derby
>> clients and servers. Derby clients and servers can interoperate
>> provided that they share the same major release number. Say that an
>> application currently runs using a client and server from the same
>> family. The application will continue to run if the client upgrades
>> to the next minor release. The application will also run if the
>> server upgrades to the next minor release.
>>
>> 3b) We strive to minimize incompatiblities across release families.
>> However, we do not guarantee that a client will interoperate with a
>> server having a different major release number. If an application
>> upgrades its client to a new major release, the server may have to
>> upgrade to the new release family too. Similarly, if an application
>> upgrades its server to a new major release, the client may need to
>> upgrade too.
>>
>
> I think this is implied in the definition of Stable and Private Stable
> interfaces, and by ensuring that all interfaces that the network
> client depends upon are marked as either Stable or Private Stable.
>
> I can imagine us providing this kind of wording in our documentation,
> but I am not sure if it is required here, I think it's already covered.
>
> I think your wording does add some clarity about when changes may
> occur, and I may add that to the note about this that I copied from
> Kathey's email onto the Wiki page.
Thanks.
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Rick Hillegas wrote:
> Hi David,
>
> 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."
>
> 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. We strive to
> minimize churn for applications migrating to the next major release of
> Derby. However these migrations may entail application changes."
>
This sounds reasonable to me, and is a summary of our stability
guarantees descrbed below
>
> 2) Bug fixing policy.
>
> I think that the Exceptions section should say explicitly that "It is OK
> for minor releases to fix bugs in our implementation of the standards,
> even if those fixes break existing applications." Bugfixes can and do
> break applications and so violate the cardinal rule. Here are some more
> examples:
>
> 2a) Wrong query results. The correct results may break applications
> which are either unaware of the problem or which have already written
> compensatory logic to patch over our error. Correct results may slow
> down the query's performance and the customer may consider this
> degradation intolerable.
>
Ooh. I can tell you speak from experience. I would actually argue that
this is not acceptable. You can't just break applications without
warning. What I have seen in the past is you provide the user to enable
the old or new behavior through some kind of flag, e.g.
derby.use.old.broken.behavior or derby.use.new.fixed.behavior
> 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.
>
I think it would be unacceptable to remove unsupported datatypes, even
if they are not spec compliant. Again, you use versioning and
capabilities negotiation to change in a compatible way. For example, if
someone has an itch to support a network client that can only handle the
types specified in DRDA, and the network client today supports
non-standard types, then we should provide an option to run in
"standard-DRDA" mode and disable those types.
If we want to add new, non-standard types, then we should only support
these types if the client explicitly says it can handle them.
>
> 3) Client/server compatibility.
>
> I would expect to find these rules spelled out on the wiki page. It is
> not clear to me that you can deduce client/server compatibility from the
> cardinal rule. Are these the rules?
I did add a note based on Kathey's comments. I think you *can* achieve
this by declaring the right interfaces as Stable or Private Stable, but
I agree it's good to call it out.
>
> 3a) A major release number defines a family of compatible Derby clients
> and servers. Derby clients and servers can interoperate provided that
> they share the same major release number. Say that an application
> currently runs using a client and server from the same family. The
> application will continue to run if the client upgrades to the next
> minor release. The application will also run if the server upgrades to
> the next minor release.
>
> 3b) We strive to minimize incompatiblities across release families.
> However, we do not guarantee that a client will interoperate with a
> server having a different major release number. If an application
> upgrades its client to a new major release, the server may have to
> upgrade to the new release family too. Similarly, if an application
> upgrades its server to a new major release, the client may need to
> upgrade too.
>
I think this is implied in the definition of Stable and Private Stable
interfaces, and by ensuring that all interfaces that the network client
depends upon are marked as either Stable or Private Stable.
I can imagine us providing this kind of wording in our documentation,
but I am not sure if it is required here, I think it's already covered.
I think your wording does add some clarity about when changes may occur,
and I may add that to the note about this that I copied from Kathey's
email onto the Wiki page.
>
> 4) Interface table.
>
> Here my pedantry goes super-nova: The Comments column for the System
> catalogs notes that adding columns is considered a compabible change.
> Parallel remarks should be added to the Comments columns for SQL
> language, JDBC, Published API, DRDA, Metadata Procedures, SQLStates,
> Tools, and various Properties: For instance, a minor release can
> implement additional SQL features, additional JDBC methods, add new
> methods to the Published API, implement additional DRDA datatypes, add
> new Metadata Procedures, add more SQLStates, add more Tools, add more
> commands and arguments to Tools, and add more Properties..
>
I think that I would rather remove this comment and have this discussion
migrated to the "What is An Incompatible Change" section, which I would
love you to review.
>
> 5) Copy editting.
>
> In the Interface Table, "Jar file manifest entires" should read "Jar
> file manifest entries".
>
OK.
> Thanks,
> -Rick
>
> David W. Van Couvering wrote:
>
>> It's been awfully quiet out there. Are there really no other opinions
>> about this. One little peep from Dan and another from Kathey, and
>> we're done? Is this the derby-dev alias I know and love?
>>
>> I mean, maybe it's just *that* good that there is no debate, but
>> somehow, I wonder...
>>
>> I'll give it another 24 hours, and if there are no other comments, I'm
>> going to basically take the contents of these page and put them up for
>> a vote. If the vote passes, I'll migrate the contents of the vote to
>> the "main" web site so that our "contracts" around these interfaces
>> stabilities are more or less set in stone, as it were.
>>
>> David
>>
>> David W. Van Couvering wrote:
>>
>>> Hi, all. I would like to propose that we have a discussion, in
>>> preparation for (at some time in the future) a vote on the interface
>>> table I put together at
>>>
>>> http://wiki.apache.org/db-derby/ForwardCompatibility
>>>
>>> The approach I was thinking of is:
>>>
>>> - everybody who is interested take a look at this table, and raise
>>> issues as needed
>>>
>>> - discussion ensues as needed
>>>
>>> - I will incrementally update the Wiki page when it seems there is a
>>> consensus on a particular issue
>>>
>>> Once things have somewhat stabilized (and where there is contention,
>>> people are starting to repeat themselves :)), I'll then I'll hold a
>>> vote. The vote email will contain the relevant text and the
>>> interface table from the Wiki page, so that we know what we're voting
>>> on and so that it ends up in the archives.
>>>
>>> This interface table would be for the next release of Derby (10.1.3
>>> or 10.2, whichever comes first).
>>>
>>> I would like to suggest that if you want to discuss the stability
>>> classification of a *particular* interface, you do so with a
>>> separate, specific email subject line, so that those who may be
>>> interested will notice and participate.
>>>
>>> How does this sound?
>>>
>>> Does anyone think we need to vote on the interface taxonomy and the
>>> definition of an interface separate from the stability
>>> classifications given to each interface?
>>>
>>> David
>>>
>>>
>>>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by Rick Hillegas <Ri...@Sun.COM>.
Hi David,
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."
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. We strive to
minimize churn for applications migrating to the next major release of
Derby. However these migrations may entail application changes."
2) Bug fixing policy.
I think that the Exceptions section should say explicitly that "It is OK
for minor releases to fix bugs in our implementation of the standards,
even if those fixes break existing applications." Bugfixes can and do
break applications and so violate the cardinal rule. Here are some more
examples:
2a) Wrong query results. The correct results may break applications
which are either unaware of the problem or which have already written
compensatory logic to patch over our error. Correct results may slow
down the query's performance and the customer may consider this
degradation intolerable.
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.
3) Client/server compatibility.
I would expect to find these rules spelled out on the wiki page. It is
not clear to me that you can deduce client/server compatibility from the
cardinal rule. Are these the rules?
3a) A major release number defines a family of compatible Derby clients
and servers. Derby clients and servers can interoperate provided that
they share the same major release number. Say that an application
currently runs using a client and server from the same family. The
application will continue to run if the client upgrades to the next
minor release. The application will also run if the server upgrades to
the next minor release.
3b) We strive to minimize incompatiblities across release families.
However, we do not guarantee that a client will interoperate with a
server having a different major release number. If an application
upgrades its client to a new major release, the server may have to
upgrade to the new release family too. Similarly, if an application
upgrades its server to a new major release, the client may need to
upgrade too.
4) Interface table.
Here my pedantry goes super-nova: The Comments column for the System
catalogs notes that adding columns is considered a compabible change.
Parallel remarks should be added to the Comments columns for SQL
language, JDBC, Published API, DRDA, Metadata Procedures, SQLStates,
Tools, and various Properties: For instance, a minor release can
implement additional SQL features, additional JDBC methods, add new
methods to the Published API, implement additional DRDA datatypes, add
new Metadata Procedures, add more SQLStates, add more Tools, add more
commands and arguments to Tools, and add more Properties..
5) Copy editting.
In the Interface Table, "Jar file manifest entires" should read "Jar
file manifest entries".
Thanks,
-Rick
David W. Van Couvering wrote:
> It's been awfully quiet out there. Are there really no other opinions
> about this. One little peep from Dan and another from Kathey, and
> we're done? Is this the derby-dev alias I know and love?
>
> I mean, maybe it's just *that* good that there is no debate, but
> somehow, I wonder...
>
> I'll give it another 24 hours, and if there are no other comments, I'm
> going to basically take the contents of these page and put them up for
> a vote. If the vote passes, I'll migrate the contents of the vote to
> the "main" web site so that our "contracts" around these interfaces
> stabilities are more or less set in stone, as it were.
>
> David
>
> David W. Van Couvering wrote:
>
>> Hi, all. I would like to propose that we have a discussion, in
>> preparation for (at some time in the future) a vote on the interface
>> table I put together at
>>
>> http://wiki.apache.org/db-derby/ForwardCompatibility
>>
>> The approach I was thinking of is:
>>
>> - everybody who is interested take a look at this table, and raise
>> issues as needed
>>
>> - discussion ensues as needed
>>
>> - I will incrementally update the Wiki page when it seems there is a
>> consensus on a particular issue
>>
>> Once things have somewhat stabilized (and where there is contention,
>> people are starting to repeat themselves :)), I'll then I'll hold a
>> vote. The vote email will contain the relevant text and the
>> interface table from the Wiki page, so that we know what we're voting
>> on and so that it ends up in the archives.
>>
>> This interface table would be for the next release of Derby (10.1.3
>> or 10.2, whichever comes first).
>>
>> I would like to suggest that if you want to discuss the stability
>> classification of a *particular* interface, you do so with a
>> separate, specific email subject line, so that those who may be
>> interested will notice and participate.
>>
>> How does this sound?
>>
>> Does anyone think we need to vote on the interface taxonomy and the
>> definition of an interface separate from the stability
>> classifications given to each interface?
>>
>> David
>>
>>
>>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
OK, I updated the page to include my pass at defining incompatible
changes. Your comments, especially those of you who have to deal with
this regularly in the field, are *much* appreciated! I particularly
need help with what it means to make compatible changes in the database
and log file formats.
David
David W. Van Couvering wrote:
> Thanks for your comments, Kathey, and yes, it can definitely wait a
> week. It was just so quiet that I thought I'd do a "ping" and see if
> there was more to come from everyone.
>
> Responses below...
>
> Kathey Marsden wrote:
>
>> I wish I had more time to look at this but I think that I would add
>> these things.
>> - In general any documented behaviour is a stable interface, unless
>> specifically documented here or in the documentation as unstable.
>
>
> I'm not sure how to handle this. What does it mean to "incompatibly
> change" documented behavior?
>
> Usually the behavior is in relation to a given interface. So perhaps in
> our definition of what it means to incompatibly change an interface
> means you can't change the documented behavior of that interface (e.g.
> the "contract" of that interface).
>
> I think it's also fair to say that unless explicitly called out in the
> table as otherwise, one can assume a publicly documented interface is
> Stable.
>
>>
>> - Derby will at a minimum negotiate down to the lower interface
>> revision level:
>> - When different versions of Derby client and server are used
>> together (in the same or different JVM's)
>> - When different jvm versions are used on client and server.
>>
>
> I think this is a solution that provides a guarantee of stability to the
> client/server interfaces. I can add this as a note, however.
>
> I think by calling out the *specific* interfaces that the client depends
> upon (DRDA, metadata procedures, system stored procedures, ???) and
> marking them as Stable or Private Stable is a Really Good Idea in our
> attempts to provide the guarantee of client/server compatiblity. Note,
> for example, some of us newbies changing the metadata procedures willy
> nilly because we were unaware of the impact on compatibility. Having
> these called out will make us all more conscious of what we can and
> can't do within the system.
>
>>
>> In the interface table I would add:
>> - Defaults returned by DatabaseMetaData methods Stable
>> - Documented defaults
>> Stable
>> - console output format for tools and network server Unstable
>> - System stored procedures
>> Stable
>>
>
> OK, I'll add these. I think the console output format for tools and
> server should actually be marked Private -- it's not documented in the
> user documentation, and can change at any time.
>
> Dumb question: are system stored procedures in the user documentation?
> If not, perhaps they should be Private Stable rather than Stable? If
> they're not documented, what is driving the requirement that they be
> stable - client/server compatibility?
>
>> Under notes It would be good to mention:
>>
>> .
>>
>
> OK
>
>
>> Could we wait a week for a vote? I think I need to study this some
>> more.
>> Thanks David for doing this.
>>
>
> Yes, sure, and you're welcome.
>
> David
>
>> Kathey
>>
>>
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Kathey Marsden <km...@sbcglobal.net>.
David W. Van Couvering wrote:
> I think it's also fair to say that unless explicitly called out in the
> table as otherwise, one can assume a publicly documented interface is
> Stable.
>
That sounds good. Just wanted to make sure there is a catch all for this.
>>
>> - Derby will at a minimum negotiate down to the lower interface
>> revision level:
>> - When different versions of Derby client and server are used
>> together (in the same or different JVM's)
>> - When different jvm versions are used on client and server.
>>
>
> I think this is a solution that provides a guarantee of stability to
> the client/server interfaces. I can add this as a note, however.
>
Yes, a note would be good for clarification.
> I think by calling out the *specific* interfaces that the client
> depends upon (DRDA, metadata procedures, system stored procedures,
> ???) and marking them as Stable or Private Stable is a Really Good
> Idea in our attempts to provide the guarantee of client/server
> compatiblity.
Agreed.
> I think the console output format for tools and server should
> actually be marked Private --
good
> are system stored procedures in the user documentation?
http://db.apache.org/derby/docs/dev/ref/crefsqlbuiltinsystemprocedures.html
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Jeff Levitt <de...@mylevita.com>.
--- "David W. Van Couvering"
<Da...@Sun.COM> wrote:
> I agree that you can't really advertise a new
> feature as really
> available unless it's documented, and that in this
> scratch-your-itch
> world, this would seem to be something that the
> person writing the
> feature would be motivated to do. I think having a
> requirement that
> some specification is required before an interface
> is considered public
> is worth considering. Of course, the other people
> who may be itching to
> document a feature are those who want to use it, so
> I could imagine it
> being a collaborative effort.
>
> I can add a note to the effect that "no interface
> can be considered a
> public interface (e.g. Stable, Unstable or Standard)
> unless it is
> documented in the user documentation". Would this
> get the point across?
>
> David
Thats a huge step in the right direction. It states
in writing the link between documentation and
stability. Perhaps the next step would be linking the
documentation in the developer's mind to their code,
so that both are one and the same.
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I agree that you can't really advertise a new feature as really
available unless it's documented, and that in this scratch-your-itch
world, this would seem to be something that the person writing the
feature would be motivated to do. I think having a requirement that
some specification is required before an interface is considered public
is worth considering. Of course, the other people who may be itching to
document a feature are those who want to use it, so I could imagine it
being a collaborative effort.
I can add a note to the effect that "no interface can be considered a
public interface (e.g. Stable, Unstable or Standard) unless it is
documented in the user documentation". Would this get the point across?
David
Jeff Levitt wrote:
> Hi David,
>
> Yes I thinnk thats what I'm trying to say. Of course
> something can be implemented and not documented, or
> the other way around, but my sense is that we are
> trying to make acontract here for ourselves, and with
> our users, and I think that if part of that contract
> is to tell our users that what they see in the doc is
> fact, then we should strive to always make that true.
> That means a new contribution would not be accepted
> unless it included corresponding documentation. If we
> add a new function then either a patch to the DITA
> source referencing that function is included, or at
> the very least a full function spec is submitted so
> that documentation can be written by someone else.
>
> The bottom line would be that documentation would be
> considered as important as codeline itself; quality
> considerations would include documentation, just as
> proper code consistency and standards are required.
>
> Most contributors are not documentation specialists,
> so maybe it is too much to ask, but I think if we are
> telling users to accept the doc as the final word,
> then we need to have some sort of MINIMUM doc
> contribution requirement. What do other people think?
>
> --- "David W. Van Couvering"
> <Da...@Sun.COM> wrote:
>
>
>>Hi, Jeff. I've been quiet on this comment because I
>>didn't fully
>>understand it.
>>
>>I *think* what you're saying is that an interface
>>can not be considered
>>Stable or Unstable unless it's actually documented.
>>Is that right?
>>
>>David
>>
>>Jeff Levitt wrote:
>>
>>>>From a documentation perspective, I think if we
>>
>>are
>>
>>>going to say on this page that items are stable AS
>>>DOCUMENTED in the user documentation, then we also
>>>need to put in some sort of requirement on this
>>
>>page
>>
>>>that says any changes made to the stability of an
>>
>>item
>>
>>>MUST be documented as well in order to be
>>
>>committed an
>>
>>>considered stable. Its not stable if its not
>>>documented and we are telling people that it is
>>
>>stable
>>
>>>as documented. Agreed?
>>>
>>>I think this is something that would be good to
>>
>>put in
>>
>>>to make sure that developers understand the
>>
>>importance
>>
>>>of documenting their work, whether its something
>>
>>new
>>
>>>or a change to something that exists, and that its
>>
>>not
>>
>>>just going to magically show up in the
>>
>>documentation
>>
>>>if they put it in the code (unless its javadoc) :)
>>>
>>>--- "David W. Van Couvering"
>>><Da...@Sun.COM> wrote:
>>>
>>>
>>>
>>>>Thanks for your comments, Kathey, and yes, it can
>>>>definitely wait a
>>>>week. It was just so quiet that I thought I'd do
>>
>>a
>>
>>>>"ping" and see if
>>>>there was more to come from everyone.
>>>>
>>>>Responses below...
>>>>
>>>>Kathey Marsden wrote:
>>>>
>>>>
>>>>>I wish I had more time to look at this but I
>>>>
>>>>think that I would add
>>>>
>>>>
>>>>>these things.
>>>>>- In general any documented behaviour is a
>>>>
>>>>stable interface, unless
>>>>
>>>>
>>>>>specifically documented here or in the
>>>>
>>>>documentation as unstable.
>>>>
>>>>I'm not sure how to handle this. What does it
>>
>>mean
>>
>>>>to "incompatibly
>>>>change" documented behavior?
>>>>
>>>>Usually the behavior is in relation to a given
>>>>interface. So perhaps in
>>>>our definition of what it means to incompatibly
>>>>change an interface
>>>>means you can't change the documented behavior of
>>>>that interface (e.g.
>>>>the "contract" of that interface).
>>>>
>>>>I think it's also fair to say that unless
>>
>>explicitly
>>
>>>>called out in the
>>>>table as otherwise, one can assume a publicly
>>>>documented interface is
>>>>Stable.
>>>>
>>>>
>>>>
>>>>>- Derby will at a minimum negotiate down to the
>>>>
>>>>lower interface
>>>>
>>>>
>>>>>revision level:
>>>>> - When different versions of Derby client
>>>>
>>>>and server are used
>>>>
>>>>
>>>>>together (in the same or different JVM's)
>>>>> - When different jvm versions are used on
>>>>
>>>>client and server.
>>>>
>>>>I think this is a solution that provides a
>>
>>guarantee
>>
>>>>of stability to the
>>>>client/server interfaces. I can add this as a
>>
>>note,
>>
>>>>however.
>>>>
>>>>I think by calling out the *specific* interfaces
>>>>that the client depends
>>>>upon (DRDA, metadata procedures, system stored
>>>>procedures, ???) and
>>>>marking them as Stable or Private Stable is a
>>
>>Really
>>
>>>>Good Idea in our
>>>>attempts to provide the guarantee of client/server
>>>>compatiblity. Note,
>>>>for example, some of us newbies changing the
>>>>metadata procedures willy
>>>>nilly because we were unaware of the impact on
>>>>compatibility. Having
>>>>these called out will make us all more conscious
>>
>>of
>>
>>>>what we can and
>>>>can't do within the system.
>>>>
>>>>
>>>>
>>>>>In the interface table I would add:
>>>>>- Defaults returned by DatabaseMetaData methods
>>
>>>> Stable
>>>>
>>>>
>>>>>- Documented defaults
>>
>>>>
>>>>
>>>>
>>>>>Stable
>>>>>- console output format for tools and network
>>>>
>>>>server Unstable
>>>>
>>>>
>>>>>- System stored procedures
>>
>>>> Stable
>>>>
>>>>OK, I'll add these. I think the console output
>>>>format for tools and
>>>>server should actually be marked Private -- it's
>>
>>not
>>
>>>>documented in the
>>>>user documentation, and can change at any time.
>>>>
>>>>Dumb question: are system stored procedures in the
>>>>user documentation?
>>>>If not, perhaps they should be Private Stable
>>
>>rather
>>
>>>>than Stable? If
>>>>they're not documented, what is driving the
>>>>requirement that they be
>>>>stable - client/server compatibility?
>>>>
>>>>
>>>>
>>>>>Under notes It would be good to mention:
>>>>>
>>>>> .
>>>>>
>>>>
>>>>OK
>>>>
>>>>
>>>>
>>>>
>>>>>Could we wait a week for a vote? I think I
>>
>>need
>>
>>>>to study this some more.
>>>>
>>>>
>>>>>Thanks David for doing this.
>>>>>
>>>>
>>>>Yes, sure, and you're welcome.
>>>>
>>>>David
>>>>
>>>>
>>>>
>>>>>Kathey
>>>>>
>>>>>
>>>>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Jeff Levitt <de...@mylevita.com>.
Hi David,
Yes I thinnk thats what I'm trying to say. Of course
something can be implemented and not documented, or
the other way around, but my sense is that we are
trying to make acontract here for ourselves, and with
our users, and I think that if part of that contract
is to tell our users that what they see in the doc is
fact, then we should strive to always make that true.
That means a new contribution would not be accepted
unless it included corresponding documentation. If we
add a new function then either a patch to the DITA
source referencing that function is included, or at
the very least a full function spec is submitted so
that documentation can be written by someone else.
The bottom line would be that documentation would be
considered as important as codeline itself; quality
considerations would include documentation, just as
proper code consistency and standards are required.
Most contributors are not documentation specialists,
so maybe it is too much to ask, but I think if we are
telling users to accept the doc as the final word,
then we need to have some sort of MINIMUM doc
contribution requirement. What do other people think?
--- "David W. Van Couvering"
<Da...@Sun.COM> wrote:
> Hi, Jeff. I've been quiet on this comment because I
> didn't fully
> understand it.
>
> I *think* what you're saying is that an interface
> can not be considered
> Stable or Unstable unless it's actually documented.
> Is that right?
>
> David
>
> Jeff Levitt wrote:
> > From a documentation perspective, I think if we
> are
> > going to say on this page that items are stable AS
> > DOCUMENTED in the user documentation, then we also
> > need to put in some sort of requirement on this
> page
> > that says any changes made to the stability of an
> item
> > MUST be documented as well in order to be
> committed an
> > considered stable. Its not stable if its not
> > documented and we are telling people that it is
> stable
> > as documented. Agreed?
> >
> > I think this is something that would be good to
> put in
> > to make sure that developers understand the
> importance
> > of documenting their work, whether its something
> new
> > or a change to something that exists, and that its
> not
> > just going to magically show up in the
> documentation
> > if they put it in the code (unless its javadoc) :)
> >
> > --- "David W. Van Couvering"
> > <Da...@Sun.COM> wrote:
> >
> >
> >>Thanks for your comments, Kathey, and yes, it can
> >>definitely wait a
> >>week. It was just so quiet that I thought I'd do
> a
> >>"ping" and see if
> >>there was more to come from everyone.
> >>
> >>Responses below...
> >>
> >>Kathey Marsden wrote:
> >>
> >>>I wish I had more time to look at this but I
> >>
> >>think that I would add
> >>
> >>>these things.
> >>> - In general any documented behaviour is a
> >>
> >>stable interface, unless
> >>
> >>>specifically documented here or in the
> >>
> >>documentation as unstable.
> >>
> >>I'm not sure how to handle this. What does it
> mean
> >>to "incompatibly
> >>change" documented behavior?
> >>
> >>Usually the behavior is in relation to a given
> >>interface. So perhaps in
> >>our definition of what it means to incompatibly
> >>change an interface
> >>means you can't change the documented behavior of
> >>that interface (e.g.
> >>the "contract" of that interface).
> >>
> >>I think it's also fair to say that unless
> explicitly
> >>called out in the
> >>table as otherwise, one can assume a publicly
> >>documented interface is
> >>Stable.
> >>
> >>
> >>>- Derby will at a minimum negotiate down to the
> >>
> >>lower interface
> >>
> >>>revision level:
> >>> - When different versions of Derby client
> >>
> >>and server are used
> >>
> >>>together (in the same or different JVM's)
> >>> - When different jvm versions are used on
> >>
> >>client and server.
> >>
> >>I think this is a solution that provides a
> guarantee
> >>of stability to the
> >>client/server interfaces. I can add this as a
> note,
> >>however.
> >>
> >>I think by calling out the *specific* interfaces
> >>that the client depends
> >>upon (DRDA, metadata procedures, system stored
> >>procedures, ???) and
> >>marking them as Stable or Private Stable is a
> Really
> >>Good Idea in our
> >>attempts to provide the guarantee of client/server
> >>compatiblity. Note,
> >>for example, some of us newbies changing the
> >>metadata procedures willy
> >>nilly because we were unaware of the impact on
> >>compatibility. Having
> >>these called out will make us all more conscious
> of
> >>what we can and
> >>can't do within the system.
> >>
> >>
> >>>In the interface table I would add:
> >>>- Defaults returned by DatabaseMetaData methods
>
> >>
> >> Stable
> >>
> >>>- Documented defaults
>
> >>
> >>
> >>
> >>>Stable
> >>>- console output format for tools and network
> >>
> >>server Unstable
> >>
> >>>- System stored procedures
>
> >>
> >> Stable
> >>
> >>OK, I'll add these. I think the console output
> >>format for tools and
> >>server should actually be marked Private -- it's
> not
> >>documented in the
> >>user documentation, and can change at any time.
> >>
> >>Dumb question: are system stored procedures in the
> >>user documentation?
> >>If not, perhaps they should be Private Stable
> rather
> >>than Stable? If
> >>they're not documented, what is driving the
> >>requirement that they be
> >>stable - client/server compatibility?
> >>
> >>
> >>>Under notes It would be good to mention:
> >>>
> >>> .
> >>>
> >>
> >>OK
> >>
> >>
> >>
> >>>Could we wait a week for a vote? I think I
> need
> >>
> >>to study this some more.
> >>
> >>>Thanks David for doing this.
> >>>
> >>
> >>Yes, sure, and you're welcome.
> >>
> >>David
> >>
> >>
> >>>Kathey
> >>>
> >>>
> >>
> >
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Jeff Levitt <de...@mylevita.com>.
P.S. David, I read my original reply and even I didn't
understand it! I think my latest response is slightly
more clear.... Sorry all,
Jeff
--- "David W. Van Couvering"
<Da...@Sun.COM> wrote:
> Hi, Jeff. I've been quiet on this comment because I
> didn't fully
> understand it.
>
> I *think* what you're saying is that an interface
> can not be considered
> Stable or Unstable unless it's actually documented.
> Is that right?
>
> David
>
> Jeff Levitt wrote:
> > From a documentation perspective, I think if we
> are
> > going to say on this page that items are stable AS
> > DOCUMENTED in the user documentation, then we also
> > need to put in some sort of requirement on this
> page
> > that says any changes made to the stability of an
> item
> > MUST be documented as well in order to be
> committed an
> > considered stable. Its not stable if its not
> > documented and we are telling people that it is
> stable
> > as documented. Agreed?
> >
> > I think this is something that would be good to
> put in
> > to make sure that developers understand the
> importance
> > of documenting their work, whether its something
> new
> > or a change to something that exists, and that its
> not
> > just going to magically show up in the
> documentation
> > if they put it in the code (unless its javadoc) :)
> >
> > --- "David W. Van Couvering"
> > <Da...@Sun.COM> wrote:
> >
> >
> >>Thanks for your comments, Kathey, and yes, it can
> >>definitely wait a
> >>week. It was just so quiet that I thought I'd do
> a
> >>"ping" and see if
> >>there was more to come from everyone.
> >>
> >>Responses below...
> >>
> >>Kathey Marsden wrote:
> >>
> >>>I wish I had more time to look at this but I
> >>
> >>think that I would add
> >>
> >>>these things.
> >>> - In general any documented behaviour is a
> >>
> >>stable interface, unless
> >>
> >>>specifically documented here or in the
> >>
> >>documentation as unstable.
> >>
> >>I'm not sure how to handle this. What does it
> mean
> >>to "incompatibly
> >>change" documented behavior?
> >>
> >>Usually the behavior is in relation to a given
> >>interface. So perhaps in
> >>our definition of what it means to incompatibly
> >>change an interface
> >>means you can't change the documented behavior of
> >>that interface (e.g.
> >>the "contract" of that interface).
> >>
> >>I think it's also fair to say that unless
> explicitly
> >>called out in the
> >>table as otherwise, one can assume a publicly
> >>documented interface is
> >>Stable.
> >>
> >>
> >>>- Derby will at a minimum negotiate down to the
> >>
> >>lower interface
> >>
> >>>revision level:
> >>> - When different versions of Derby client
> >>
> >>and server are used
> >>
> >>>together (in the same or different JVM's)
> >>> - When different jvm versions are used on
> >>
> >>client and server.
> >>
> >>I think this is a solution that provides a
> guarantee
> >>of stability to the
> >>client/server interfaces. I can add this as a
> note,
> >>however.
> >>
> >>I think by calling out the *specific* interfaces
> >>that the client depends
> >>upon (DRDA, metadata procedures, system stored
> >>procedures, ???) and
> >>marking them as Stable or Private Stable is a
> Really
> >>Good Idea in our
> >>attempts to provide the guarantee of client/server
> >>compatiblity. Note,
> >>for example, some of us newbies changing the
> >>metadata procedures willy
> >>nilly because we were unaware of the impact on
> >>compatibility. Having
> >>these called out will make us all more conscious
> of
> >>what we can and
> >>can't do within the system.
> >>
> >>
> >>>In the interface table I would add:
> >>>- Defaults returned by DatabaseMetaData methods
>
> >>
> >> Stable
> >>
> >>>- Documented defaults
>
> >>
> >>
> >>
> >>>Stable
> >>>- console output format for tools and network
> >>
> >>server Unstable
> >>
> >>>- System stored procedures
>
> >>
> >> Stable
> >>
> >>OK, I'll add these. I think the console output
> >>format for tools and
> >>server should actually be marked Private -- it's
> not
> >>documented in the
> >>user documentation, and can change at any time.
> >>
> >>Dumb question: are system stored procedures in the
> >>user documentation?
> >>If not, perhaps they should be Private Stable
> rather
> >>than Stable? If
> >>they're not documented, what is driving the
> >>requirement that they be
> >>stable - client/server compatibility?
> >>
> >>
> >>>Under notes It would be good to mention:
> >>>
> >>> .
> >>>
> >>
> >>OK
> >>
> >>
> >>
> >>>Could we wait a week for a vote? I think I
> need
> >>
> >>to study this some more.
> >>
> >>>Thanks David for doing this.
> >>>
> >>
> >>Yes, sure, and you're welcome.
> >>
> >>David
> >>
> >>
> >>>Kathey
> >>>
> >>>
> >>
> >
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Hi, Jeff. I've been quiet on this comment because I didn't fully
understand it.
I *think* what you're saying is that an interface can not be considered
Stable or Unstable unless it's actually documented. Is that right?
David
Jeff Levitt wrote:
> From a documentation perspective, I think if we are
> going to say on this page that items are stable AS
> DOCUMENTED in the user documentation, then we also
> need to put in some sort of requirement on this page
> that says any changes made to the stability of an item
> MUST be documented as well in order to be committed an
> considered stable. Its not stable if its not
> documented and we are telling people that it is stable
> as documented. Agreed?
>
> I think this is something that would be good to put in
> to make sure that developers understand the importance
> of documenting their work, whether its something new
> or a change to something that exists, and that its not
> just going to magically show up in the documentation
> if they put it in the code (unless its javadoc) :)
>
> --- "David W. Van Couvering"
> <Da...@Sun.COM> wrote:
>
>
>>Thanks for your comments, Kathey, and yes, it can
>>definitely wait a
>>week. It was just so quiet that I thought I'd do a
>>"ping" and see if
>>there was more to come from everyone.
>>
>>Responses below...
>>
>>Kathey Marsden wrote:
>>
>>>I wish I had more time to look at this but I
>>
>>think that I would add
>>
>>>these things.
>>> - In general any documented behaviour is a
>>
>>stable interface, unless
>>
>>>specifically documented here or in the
>>
>>documentation as unstable.
>>
>>I'm not sure how to handle this. What does it mean
>>to "incompatibly
>>change" documented behavior?
>>
>>Usually the behavior is in relation to a given
>>interface. So perhaps in
>>our definition of what it means to incompatibly
>>change an interface
>>means you can't change the documented behavior of
>>that interface (e.g.
>>the "contract" of that interface).
>>
>>I think it's also fair to say that unless explicitly
>>called out in the
>>table as otherwise, one can assume a publicly
>>documented interface is
>>Stable.
>>
>>
>>>- Derby will at a minimum negotiate down to the
>>
>>lower interface
>>
>>>revision level:
>>> - When different versions of Derby client
>>
>>and server are used
>>
>>>together (in the same or different JVM's)
>>> - When different jvm versions are used on
>>
>>client and server.
>>
>>I think this is a solution that provides a guarantee
>>of stability to the
>>client/server interfaces. I can add this as a note,
>>however.
>>
>>I think by calling out the *specific* interfaces
>>that the client depends
>>upon (DRDA, metadata procedures, system stored
>>procedures, ???) and
>>marking them as Stable or Private Stable is a Really
>>Good Idea in our
>>attempts to provide the guarantee of client/server
>>compatiblity. Note,
>>for example, some of us newbies changing the
>>metadata procedures willy
>>nilly because we were unaware of the impact on
>>compatibility. Having
>>these called out will make us all more conscious of
>>what we can and
>>can't do within the system.
>>
>>
>>>In the interface table I would add:
>>>- Defaults returned by DatabaseMetaData methods
>>
>> Stable
>>
>>>- Documented defaults
>>
>>
>>
>>>Stable
>>>- console output format for tools and network
>>
>>server Unstable
>>
>>>- System stored procedures
>>
>> Stable
>>
>>OK, I'll add these. I think the console output
>>format for tools and
>>server should actually be marked Private -- it's not
>>documented in the
>>user documentation, and can change at any time.
>>
>>Dumb question: are system stored procedures in the
>>user documentation?
>>If not, perhaps they should be Private Stable rather
>>than Stable? If
>>they're not documented, what is driving the
>>requirement that they be
>>stable - client/server compatibility?
>>
>>
>>>Under notes It would be good to mention:
>>>
>>> .
>>>
>>
>>OK
>>
>>
>>
>>>Could we wait a week for a vote? I think I need
>>
>>to study this some more.
>>
>>>Thanks David for doing this.
>>>
>>
>>Yes, sure, and you're welcome.
>>
>>David
>>
>>
>>>Kathey
>>>
>>>
>>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Jeff Levitt <de...@mylevita.com>.
>From a documentation perspective, I think if we are
going to say on this page that items are stable AS
DOCUMENTED in the user documentation, then we also
need to put in some sort of requirement on this page
that says any changes made to the stability of an item
MUST be documented as well in order to be committed an
considered stable. Its not stable if its not
documented and we are telling people that it is stable
as documented. Agreed?
I think this is something that would be good to put in
to make sure that developers understand the importance
of documenting their work, whether its something new
or a change to something that exists, and that its not
just going to magically show up in the documentation
if they put it in the code (unless its javadoc) :)
--- "David W. Van Couvering"
<Da...@Sun.COM> wrote:
> Thanks for your comments, Kathey, and yes, it can
> definitely wait a
> week. It was just so quiet that I thought I'd do a
> "ping" and see if
> there was more to come from everyone.
>
> Responses below...
>
> Kathey Marsden wrote:
> > I wish I had more time to look at this but I
> think that I would add
> > these things.
> > - In general any documented behaviour is a
> stable interface, unless
> > specifically documented here or in the
> documentation as unstable.
>
> I'm not sure how to handle this. What does it mean
> to "incompatibly
> change" documented behavior?
>
> Usually the behavior is in relation to a given
> interface. So perhaps in
> our definition of what it means to incompatibly
> change an interface
> means you can't change the documented behavior of
> that interface (e.g.
> the "contract" of that interface).
>
> I think it's also fair to say that unless explicitly
> called out in the
> table as otherwise, one can assume a publicly
> documented interface is
> Stable.
>
> >
> > - Derby will at a minimum negotiate down to the
> lower interface
> > revision level:
> > - When different versions of Derby client
> and server are used
> > together (in the same or different JVM's)
> > - When different jvm versions are used on
> client and server.
> >
>
> I think this is a solution that provides a guarantee
> of stability to the
> client/server interfaces. I can add this as a note,
> however.
>
> I think by calling out the *specific* interfaces
> that the client depends
> upon (DRDA, metadata procedures, system stored
> procedures, ???) and
> marking them as Stable or Private Stable is a Really
> Good Idea in our
> attempts to provide the guarantee of client/server
> compatiblity. Note,
> for example, some of us newbies changing the
> metadata procedures willy
> nilly because we were unaware of the impact on
> compatibility. Having
> these called out will make us all more conscious of
> what we can and
> can't do within the system.
>
> >
> > In the interface table I would add:
> > - Defaults returned by DatabaseMetaData methods
> Stable
> > - Documented defaults
>
> > Stable
> > - console output format for tools and network
> server Unstable
> > - System stored procedures
> Stable
> >
>
> OK, I'll add these. I think the console output
> format for tools and
> server should actually be marked Private -- it's not
> documented in the
> user documentation, and can change at any time.
>
> Dumb question: are system stored procedures in the
> user documentation?
> If not, perhaps they should be Private Stable rather
> than Stable? If
> they're not documented, what is driving the
> requirement that they be
> stable - client/server compatibility?
>
> > Under notes It would be good to mention:
> >
> > .
> >
>
> OK
>
>
> > Could we wait a week for a vote? I think I need
> to study this some more.
> > Thanks David for doing this.
> >
>
> Yes, sure, and you're welcome.
>
> David
>
> > Kathey
> >
> >
>
Re: [doc: System stored procedures] WAS: Should we vote on it?
Posted by Knut Anders Hatlen <Kn...@Sun.COM>.
Jeff Levitt <de...@mylevita.com> writes:
> --- "David W. Van Couvering"
> <Da...@Sun.COM> wrote:
> <snip>
>>
>> Dumb question: are system stored procedures in the
>> user documentation?
>> If not, perhaps they should be Private Stable rather
>> than Stable? If
>> they're not documented, what is driving the
>> requirement that they be
>> stable - client/server compatibility?
> </snip>
>
> Is this what you were looking for David? This is in
> the Reference Manual:
>
> http://db.apache.org/derby/docs/dev/ref/crefsqlbuiltinsystemprocedures.html
These are not the only system procedures. The ones in the SYSIBM
schema are not documented, but they should be stable as well so that
we don't break client/server compatibility.
--
Knut Anders
Re: [doc: System stored procedures] WAS: Should we vote on it?
Posted by "Dag H. Wanvik" <Da...@Sun.COM>.
Jeff Levitt <de...@mylevita.com> writes:
> http://db.apache.org/derby/docs/dev/ref/crefsqlbuiltinsystemprocedures.html
There seems to be some links that are broken on this page:
# SYSC_UTIL.SYSCS_ONLINE_BACKUP_DATABASE_NOWAIT
# SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE
# SYSC_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT
# SYSCS_UTIL.SYSCS_DISABLE_LOG_ARCHIVE_MODE
The SYSC_UTIL should be SYSCS_UTIL also, I presume.
Dag
[doc: System stored procedures] WAS: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Jeff Levitt <de...@mylevita.com>.
--- "David W. Van Couvering"
<Da...@Sun.COM> wrote:
<snip>
>
> Dumb question: are system stored procedures in the
> user documentation?
> If not, perhaps they should be Private Stable rather
> than Stable? If
> they're not documented, what is driving the
> requirement that they be
> stable - client/server compatibility?
</snip>
Is this what you were looking for David? This is in
the Reference Manual:
http://db.apache.org/derby/docs/dev/ref/crefsqlbuiltinsystemprocedures.html
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Thanks for your comments, Kathey, and yes, it can definitely wait a
week. It was just so quiet that I thought I'd do a "ping" and see if
there was more to come from everyone.
Responses below...
Kathey Marsden wrote:
> I wish I had more time to look at this but I think that I would add
> these things.
> - In general any documented behaviour is a stable interface, unless
> specifically documented here or in the documentation as unstable.
I'm not sure how to handle this. What does it mean to "incompatibly
change" documented behavior?
Usually the behavior is in relation to a given interface. So perhaps in
our definition of what it means to incompatibly change an interface
means you can't change the documented behavior of that interface (e.g.
the "contract" of that interface).
I think it's also fair to say that unless explicitly called out in the
table as otherwise, one can assume a publicly documented interface is
Stable.
>
> - Derby will at a minimum negotiate down to the lower interface
> revision level:
> - When different versions of Derby client and server are used
> together (in the same or different JVM's)
> - When different jvm versions are used on client and server.
>
I think this is a solution that provides a guarantee of stability to the
client/server interfaces. I can add this as a note, however.
I think by calling out the *specific* interfaces that the client depends
upon (DRDA, metadata procedures, system stored procedures, ???) and
marking them as Stable or Private Stable is a Really Good Idea in our
attempts to provide the guarantee of client/server compatiblity. Note,
for example, some of us newbies changing the metadata procedures willy
nilly because we were unaware of the impact on compatibility. Having
these called out will make us all more conscious of what we can and
can't do within the system.
>
> In the interface table I would add:
> - Defaults returned by DatabaseMetaData methods Stable
> - Documented defaults
> Stable
> - console output format for tools and network server Unstable
> - System stored procedures Stable
>
OK, I'll add these. I think the console output format for tools and
server should actually be marked Private -- it's not documented in the
user documentation, and can change at any time.
Dumb question: are system stored procedures in the user documentation?
If not, perhaps they should be Private Stable rather than Stable? If
they're not documented, what is driving the requirement that they be
stable - client/server compatibility?
> Under notes It would be good to mention:
>
> .
>
OK
> Could we wait a week for a vote? I think I need to study this some more.
> Thanks David for doing this.
>
Yes, sure, and you're welcome.
David
> Kathey
>
>
Re: Should we vote on it? (was Re: Discussion (in preparation for
a vote) on interface stability table)
Posted by Kathey Marsden <km...@sbcglobal.net>.
David W. Van Couvering wrote:
> Just to be clear, what we'd be voting on would be not only the various
> definitions of interface stability but *also*, for each declared
> interface, the level of stability we as a community are agreeing to
> support. This can then guide decisions by developers and reviewers as
> to whether a change to a given interface can be accepted or not.
>
> David
>
> David W. Van Couvering wrote:
>
>> It's been awfully quiet out there. Are there really no other
>> opinions about this. One little peep from Dan and another from
>> Kathey, and we're done? Is this the derby-dev alias I know and love?
>>
>> I mean, maybe it's just *that* good that there is no debate, but
>> somehow, I wonder...
>>
>> I'll give it another 24 hours, and if there are no other comments,
>> I'm going to basically take the contents of these page and put them
>> up for a vote. If the vote passes, I'll migrate the contents of the
>> vote to the "main" web site so that our "contracts" around these
>> interfaces stabilities are more or less set in stone, as it were.
>>
>> David
>>
>> David W. Van Couvering wrote:
>>
>>> Hi, all. I would like to propose that we have a discussion, in
>>> preparation for (at some time in the future) a vote on the interface
>>> table I put together at
>>>
>>> http://wiki.apache.org/db-derby/ForwardCompatibility
>>>
>>> The approach I was thinking of is:
>>>
>>> - everybody who is interested take a look at this table, and raise
>>> issues as needed
>>>
>>> - discussion ensues as needed
>>>
>>> - I will incrementally update the Wiki page when it seems there is a
>>> consensus on a particular issue
>>>
>>> Once things have somewhat stabilized (and where there is contention,
>>> people are starting to repeat themselves :)), I'll then I'll hold a
>>> vote. The vote email will contain the relevant text and the
>>> interface table from the Wiki page, so that we know what we're
>>> voting on and so that it ends up in the archives.
>>>
>>> This interface table would be for the next release of Derby (10.1.3
>>> or 10.2, whichever comes first).
>>>
>>> I would like to suggest that if you want to discuss the stability
>>> classification of a *particular* interface, you do so with a
>>> separate, specific email subject line, so that those who may be
>>> interested will notice and participate.
>>>
>>> How does this sound?
>>>
>>> Does anyone think we need to vote on the interface taxonomy and the
>>> definition of an interface separate from the stability
>>> classifications given to each interface?
>>
I wish I had more time to look at this but I think that I would add
these things.
- In general any documented behaviour is a stable interface, unless
specifically documented here or in the documentation as unstable.
- Derby will at a minimum negotiate down to the lower interface
revision level:
- When different versions of Derby client and server are used
together (in the same or different JVM's)
- When different jvm versions are used on client and server.
In the interface table I would add:
- Defaults returned by DatabaseMetaData methods Stable
- Documented defaults
Stable
- console output format for tools and network server Unstable
- System stored procedures Stable
Under notes It would be good to mention:
The Derby development community voted that network client driver will be
changed to match embedded where possible for implementation defined
behaviour.
Could we wait a week for a vote? I think I need to study this some more.
Thanks David for doing this.
Kathey
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Just to be clear, what we'd be voting on would be not only the various
definitions of interface stability but *also*, for each declared
interface, the level of stability we as a community are agreeing to
support. This can then guide decisions by developers and reviewers as
to whether a change to a given interface can be accepted or not.
David
David W. Van Couvering wrote:
> It's been awfully quiet out there. Are there really no other opinions
> about this. One little peep from Dan and another from Kathey, and we're
> done? Is this the derby-dev alias I know and love?
>
> I mean, maybe it's just *that* good that there is no debate, but
> somehow, I wonder...
>
> I'll give it another 24 hours, and if there are no other comments, I'm
> going to basically take the contents of these page and put them up for a
> vote. If the vote passes, I'll migrate the contents of the vote to the
> "main" web site so that our "contracts" around these interfaces
> stabilities are more or less set in stone, as it were.
>
> David
>
> David W. Van Couvering wrote:
>
>> Hi, all. I would like to propose that we have a discussion, in
>> preparation for (at some time in the future) a vote on the interface
>> table I put together at
>>
>> http://wiki.apache.org/db-derby/ForwardCompatibility
>>
>> The approach I was thinking of is:
>>
>> - everybody who is interested take a look at this table, and raise
>> issues as needed
>>
>> - discussion ensues as needed
>>
>> - I will incrementally update the Wiki page when it seems there is a
>> consensus on a particular issue
>>
>> Once things have somewhat stabilized (and where there is contention,
>> people are starting to repeat themselves :)), I'll then I'll hold a
>> vote. The vote email will contain the relevant text and the interface
>> table from the Wiki page, so that we know what we're voting on and so
>> that it ends up in the archives.
>>
>> This interface table would be for the next release of Derby (10.1.3 or
>> 10.2, whichever comes first).
>>
>> I would like to suggest that if you want to discuss the stability
>> classification of a *particular* interface, you do so with a separate,
>> specific email subject line, so that those who may be interested will
>> notice and participate.
>>
>> How does this sound?
>>
>> Does anyone think we need to vote on the interface taxonomy and the
>> definition of an interface separate from the stability classifications
>> given to each interface?
>>
>> David
>>
>>
>>
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I am also realizing that we should send this Wiki page to the derby-user
list for review. I suspect our users will have a definite opinion about
what we're claiming to keep stable and what we're not.
David
Andrew McIntyre wrote:
> On 3/30/06, David W. Van Couvering <Da...@sun.com> wrote:
>
>> > Just on first glance the table is fairly restrictive, but generally
>> > looks good. I would think that environment variables and install
>> > directory hierarchy would be marked unstable, since it seems
>> > reasonable that we could change our use of environment variables
>> > (since they're only used in the scripts) or move things around in the
>> > distributions between minor releases.
>>
>>Isn't it possible that scripts written by our users would also make use
>>of (e.g. set) environment variables and depend on the install directory
>>hierarchy? That said, as long as we're clear as to how stable these
>>interfaces are, our users can be made aware of that and take the
>>necessary precautions (like define directory paths in a variable rather
>>than hardcode them).
>
>
> I don't think much change will actually be happening to either the
> variables or layout, I just don't think it is unreasonable to be able
> to change them significantly, if we wanted to, in a minor release,
> since they are not "core" APIs as such. I would certainly expect them
> to remain stable for maintenance/point releases, though.
>
> andrew
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
OK, I'm game for marking environment variables and directory hierarchy
Unstable.
Any comments on the stability for SQLStates?
David
Andrew McIntyre wrote:
> On 3/30/06, David W. Van Couvering <Da...@sun.com> wrote:
>
>> > Just on first glance the table is fairly restrictive, but generally
>> > looks good. I would think that environment variables and install
>> > directory hierarchy would be marked unstable, since it seems
>> > reasonable that we could change our use of environment variables
>> > (since they're only used in the scripts) or move things around in the
>> > distributions between minor releases.
>>
>>Isn't it possible that scripts written by our users would also make use
>>of (e.g. set) environment variables and depend on the install directory
>>hierarchy? That said, as long as we're clear as to how stable these
>>interfaces are, our users can be made aware of that and take the
>>necessary precautions (like define directory paths in a variable rather
>>than hardcode them).
>
>
> I don't think much change will actually be happening to either the
> variables or layout, I just don't think it is unreasonable to be able
> to change them significantly, if we wanted to, in a minor release,
> since they are not "core" APIs as such. I would certainly expect them
> to remain stable for maintenance/point releases, though.
>
> andrew
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Andrew McIntyre <mc...@gmail.com>.
On 3/30/06, David W. Van Couvering <Da...@sun.com> wrote:
>
> > Just on first glance the table is fairly restrictive, but generally
> > looks good. I would think that environment variables and install
> > directory hierarchy would be marked unstable, since it seems
> > reasonable that we could change our use of environment variables
> > (since they're only used in the scripts) or move things around in the
> > distributions between minor releases.
>
> Isn't it possible that scripts written by our users would also make use
> of (e.g. set) environment variables and depend on the install directory
> hierarchy? That said, as long as we're clear as to how stable these
> interfaces are, our users can be made aware of that and take the
> necessary precautions (like define directory paths in a variable rather
> than hardcode them).
I don't think much change will actually be happening to either the
variables or layout, I just don't think it is unreasonable to be able
to change them significantly, if we wanted to, in a minor release,
since they are not "core" APIs as such. I would certainly expect them
to remain stable for maintenance/point releases, though.
andrew
Re: Should we vote on it? (was Re: Discussion (in preparation for a
vote) on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Great comments, thanks
Andrew McIntyre wrote:
> On 3/30/06, David W. Van Couvering <Da...@sun.com> wrote:
>
>>It's been awfully quiet out there. Are there really no other opinions
>>about this. One little peep from Dan and another from Kathey, and we're
>>done? Is this the derby-dev alias I know and love?
>
>
> :-) sorry, I've been distracted by other things.
>
> Do you have a definition for "incompatible change"? Can you describe
> what threshold a change has to cross to be an "incompatible change",
> and how that is measured? Is it a result of tests, running tools, or
> what? I'd like to see a more firm definition of that term.
Yes, I agree that is missing. I think what an incompatible change means
depends upon the type of interface. I'll try and write something up.
That in itself will I am sure engender a lot of discussion. I'll see if
definitions already exist for some types of interfaces, rather than
making it all up from scratch.
>
> Just on first glance the table is fairly restrictive, but generally
> looks good. I would think that environment variables and install
> directory hierarchy would be marked unstable, since it seems
> reasonable that we could change our use of environment variables
> (since they're only used in the scripts) or move things around in the
> distributions between minor releases.
Isn't it possible that scripts written by our users would also make use
of (e.g. set) environment variables and depend on the install directory
hierarchy? That said, as long as we're clear as to how stable these
interfaces are, our users can be made aware of that and take the
necessary precautions (like define directory paths in a variable rather
than hardcode them).
>
> In general, I like it. It looks like it should lead to more sensible
> deprecation of unused or changing features. I'm curious if others feel
> that only removing deprecated features at major release boundaries is
> a requirement, or if "keep for x number of releases" might be
> acceptable.
I think this makes sense, especially if we end up not doing a major
release for 10 years like Solaris...
David
>
> andrew
Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Posted by Andrew McIntyre <mc...@gmail.com>.
On 3/30/06, David W. Van Couvering <Da...@sun.com> wrote:
> It's been awfully quiet out there. Are there really no other opinions
> about this. One little peep from Dan and another from Kathey, and we're
> done? Is this the derby-dev alias I know and love?
:-) sorry, I've been distracted by other things.
Do you have a definition for "incompatible change"? Can you describe
what threshold a change has to cross to be an "incompatible change",
and how that is measured? Is it a result of tests, running tools, or
what? I'd like to see a more firm definition of that term.
Just on first glance the table is fairly restrictive, but generally
looks good. I would think that environment variables and install
directory hierarchy would be marked unstable, since it seems
reasonable that we could change our use of environment variables
(since they're only used in the scripts) or move things around in the
distributions between minor releases.
In general, I like it. It looks like it should lead to more sensible
deprecation of unused or changing features. I'm curious if others feel
that only removing deprecated features at major release boundaries is
a requirement, or if "keep for x number of releases" might be
acceptable.
andrew
Should we vote on it? (was Re: Discussion (in preparation for a vote)
on interface stability table)
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
It's been awfully quiet out there. Are there really no other opinions
about this. One little peep from Dan and another from Kathey, and we're
done? Is this the derby-dev alias I know and love?
I mean, maybe it's just *that* good that there is no debate, but
somehow, I wonder...
I'll give it another 24 hours, and if there are no other comments, I'm
going to basically take the contents of these page and put them up for a
vote. If the vote passes, I'll migrate the contents of the vote to the
"main" web site so that our "contracts" around these interfaces
stabilities are more or less set in stone, as it were.
David
David W. Van Couvering wrote:
> Hi, all. I would like to propose that we have a discussion, in
> preparation for (at some time in the future) a vote on the interface
> table I put together at
>
> http://wiki.apache.org/db-derby/ForwardCompatibility
>
> The approach I was thinking of is:
>
> - everybody who is interested take a look at this table, and raise
> issues as needed
>
> - discussion ensues as needed
>
> - I will incrementally update the Wiki page when it seems there is a
> consensus on a particular issue
>
> Once things have somewhat stabilized (and where there is contention,
> people are starting to repeat themselves :)), I'll then I'll hold a
> vote. The vote email will contain the relevant text and the interface
> table from the Wiki page, so that we know what we're voting on and so
> that it ends up in the archives.
>
> This interface table would be for the next release of Derby (10.1.3 or
> 10.2, whichever comes first).
>
> I would like to suggest that if you want to discuss the stability
> classification of a *particular* interface, you do so with a separate,
> specific email subject line, so that those who may be interested will
> notice and participate.
>
> How does this sound?
>
> Does anyone think we need to vote on the interface taxonomy and the
> definition of an interface separate from the stability classifications
> given to each interface?
>
> David
>
>
>
Re: Discussion (in preparation for a vote) on interface stability table
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
Daniel John Debrunner wrote:
> David W. Van Couvering wrote:
>
>
>>Hi, all. I would like to propose that we have a discussion, in
>>preparation for (at some time in the future) a vote on the interface
>>table I put together at
>>
>>http://wiki.apache.org/db-derby/ForwardCompatibility
>
>
Well, I don't think I'm the final arbiter of these answers, but here's
what I would propose. I can add these questions and answers to an "FAQ"
at the end of the document.
> Would this set of rules drive the decision of when to
> declare a major release versus a minor release?
I think they would be one of the deciding factors, likely a major
deciding factor. I suspect other factors will be involved.
>
> We currently don't have any rules about when we would
> change to 11.0 from the current 10.x pattern.
I think making an incompatible change to a Stable interface would
require us to change to 11.0
>
> Would it be because someone changed some "Standard" interface
> in an incompatible way that we move to 11.0?
If a standards body makes an incompatible change to a standard interface
that we rely on, and we make the choice to upgrade to the new,
incompatible revision of that standard, then, yes, I think we should
move to a new major release. I think that a standards body making an
incompatible change to a standard is fairly rare, however.
>
> If no-one made such a change, would be be having 10.14 in a number of years?
>
Yes, I think that's reasonable, unless for "marketing" reasons we want
to upgrade the version. Solaris 10 is actually Solaris 2.10. Solaris
has been at the major revision of 2 for I think over 10 years.
David
> Curious,
> Dan.
>
>
>
>
>
Re: Discussion (in preparation for a vote) on interface stability table
Posted by "David W. Van Couvering" <Da...@Sun.COM>.
I agree we need to address client/server compatibility, but my hope is
that this is addressed by defining the appropriate stability levels for
the interfaces that the client depends upon. I am guessing this
includes DRDA, the metadata stored procedures, and probably some others.
So when you look at the interface list, make sure (a) every interface
the client depends upon is called out and (b) that these interfaces are
declared as Stable or Private Stable (a new classification I just added).
I think even after a major release we should strive for backwards
compatibility with clients. However, if we *do* need to make an
incompatible change (God forbid) then we would need to make it at a
major release and document clearly the incompatible change.
David
Kathey Marsden wrote:
> Daniel John Debrunner wrote:
>
>
>>David W. Van Couvering wrote:
>>
>>
>>
>>
>>>Hi, all. I would like to propose that we have a discussion, in
>>>preparation for (at some time in the future) a vote on the interface
>>>table I put together at
>>>
>>>http://wiki.apache.org/db-derby/ForwardCompatibility
>>>
>>>
>>
>>
>>
>
> I think we need something about client/sever compatibility. How long
> will different client/sever combinations be supported? When will we
> negotiate down vs throw an error? The same questions apply for
> client/server differences in jvm version. Should that information be
> on a different page or this one? I prefer a timed based support (e.g.
> five years) rather than a decision based on Derby versions.
>
> Kathey
>
>
>
Re: Discussion (in preparation for a vote) on interface stability
table
Posted by Kathey Marsden <km...@sbcglobal.net>.
Daniel John Debrunner wrote:
>David W. Van Couvering wrote:
>
>
>
>>Hi, all. I would like to propose that we have a discussion, in
>>preparation for (at some time in the future) a vote on the interface
>>table I put together at
>>
>>http://wiki.apache.org/db-derby/ForwardCompatibility
>>
>>
>
>
>
I think we need something about client/sever compatibility. How long
will different client/sever combinations be supported? When will we
negotiate down vs throw an error? The same questions apply for
client/server differences in jvm version. Should that information be
on a different page or this one? I prefer a timed based support (e.g.
five years) rather than a decision based on Derby versions.
Kathey
Re: Discussion (in preparation for a vote) on interface stability
table
Posted by Daniel John Debrunner <dj...@apache.org>.
David W. Van Couvering wrote:
> Hi, all. I would like to propose that we have a discussion, in
> preparation for (at some time in the future) a vote on the interface
> table I put together at
>
> http://wiki.apache.org/db-derby/ForwardCompatibility
Would this set of rules drive the decision of when to
declare a major release versus a minor release?
We currently don't have any rules about when we would
change to 11.0 from the current 10.x pattern.
Would it be because someone changed some "Standard" interface
in an incompatible way that we move to 11.0?
If no-one made such a change, would be be having 10.14 in a number of years?
Curious,
Dan.