Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Under Deprecated there is: "A deprecated interface may be removed from the project after four minor and/or major releases." http://wiki.apache.org/db-derby/ForwardCompatibility#head-b94fc1d3af5d38a917e2b6c754a8c4213e28f06e Not sure that really works. With an open source project there could be four releases in a couple of months, would allow features to be deprecated very quickly. Not sure of any better wording. Dan.
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
David Van Couvering wrote: Hi, Kathey, my silence (and I'm guessing the silence of others) was general approval of your comments. Did you update the page? I didn't see any change notifications fly by. Finally did it. What kind of clarification are you looking for? I'm afraid I'm missing your point :( nevermind. Probably not important. No time to pursue now.
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
David Van Couvering wrote: > > > Rick Hillegas wrote: >> >> I can see that Private Stable applies to the client/server api. These >> apis should remain forward/backward compatible within a release >> family. Do Private Stable interfaces turn up in other situations? > > > Yes, that's right. I wonder if the database file format is also Private > Stable. I am still looking for some guidance in that area in terms of > what are incompatible changes... What guidance do you need above: http://db.apache.org/derby/papers/versionupgrade.html ? (note there is a type in that document, at one point it has 'EM <= 10', I think that should be 'EM >= 10'.) I think that's the policy for on-disk format and did undergo a vote (I believe). Dan.
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Knut Anders Hatlen wrote: > Daniel John Debrunner <[EMAIL PROTECTED]> writes: > > >>David Van Couvering wrote: >> >>>Good news Lance, thanks, I was getting worried if we were going to have >>>to regularly change column order and break existing applications/IDEs/etc. >> >>Hopefully we don't have any documented Derby specific additional columns >>in the metadata, that would be non-standard. > > > The only non-standard columns we have are METHOD_ID and PARAMETER_ID > in getProcedureColumns and getFunctionParameters. For > getProcedureColumns, they are documented in the reference manual. Yes they are documented, but not in any useful way. There is no description of what they represent, only the text: "a Derby-specific column". I think METHOD_ID could be removed, it's an artifact of the old way Cloudscape used to support non-standard method aliases. Dan.
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Rick Hillegas wrote: David Van Couvering wrote: Rick Hillegas wrote: Hi David, I had a couple more comments on the compatibility commitments. Cheers-Rick - Changes to stored procedures: We will have to change column order if we add Derby-specific columns to a metadata ResultSet and then a later JDBC also adds more columns. See Lance's email; OK to leave as is? I thought the gist of Lance's response was this: It's ok to add vendor-specific columns to metadata ResultSets. However, the leading columns of the ResultSet must be the columns described in the JDBC spec and those columns must appear in the specified order. After that the order of vendor-specific columns doesn't matter. However, the names of those vendor-specific columns do matter; those names are the stable interface. I don't think the existing text on the compatibility webpage captures this. OK, I'll work on that - Changes to Database Tables: We should be allowed to drop indexes on System tables. OK - Changes to Command Line Interfaces. I don't understand why error message text can't be changed. This contradicts what is said in the Interface Table below. Hm, good point. I suppose changing the error message text *is* an incompatible change, but given that the interface is private, it's OK to do it. But it is a confusing message. Any suggestions? I can (a) remove error message text from the list of incompatible changes (b) keep it, but clarify that this is a private interface (c) make error message text a public interface My vote is for (a). Anyone disagree? That's my vote too, thanks. OK - Other miscellaneous formats. I'm not clear on what these miscellaneou files and strings are. For example, I'd like to make sure that we're not enshrining the current RUNTIMESTATISTICS output. Again, I think this goes back to the same point. It's not clear what the relationship is to the classification of an interface in the interfaces table and what it means to make an incompatible change. I think you're assuming incompatible changes can only apply to public interfaces, because it's really kind of moot/inapplicable for private interfaces. I think there's value in describing what it means to make an incompatible interface change, but I think the ultimate "truth" in terms of what we actually support in terms of interface stability across releases is described in the interfaces table. I think some text in the "incompatible changes" section clarifying this would be helpful. Any thoughts? I can see that Private Stable applies to the client/server api. These apis should remain forward/backward compatible within a release family. Do Private Stable interfaces turn up in other situations? Yes, that's right. I wonder if the database file format is also Private Stable. I am still looking for some guidance in that area in terms of what are incompatible changes... David - Interface table: o Shouldn't the public client api be stable like the embedded api? Yes o What is meant by "Defaults returned by DatabaseMetadata methods"? I don't know, I think I put this in as feedback from someone else. Can anyone clarify? o I think that the format of RUNTIMESTATISTICS output is unstable. OK, anyone disagree? Thanks for your review, Rick! David David Van Couvering wrote: Hi, all. I am thinking of setting up two separate votes based on the Wiki page at http://wiki.apache.org/db-derby/ForwardCompatibility The first one would be on our overall model/approach to making compatibility commitments, as described in the Wiki page. The second would be specifically for the interface table, targetted at the 10.2 release. The reason for separating these out is because, for each release, we should update the interface table and have a new vote; the overall model/approach does not need to be updated or voted on for each release. I would copy the appropriate text directly into the email for the vote, so that the thing we're voting on is a frozen snapshot, not a live document like the Wiki page. I'd like your feedback on this approach. I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. Thanks, David
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
David Van Couvering wrote: Rick Hillegas wrote: Hi David, I had a couple more comments on the compatibility commitments. Cheers-Rick - Changes to stored procedures: We will have to change column order if we add Derby-specific columns to a metadata ResultSet and then a later JDBC also adds more columns. See Lance's email; OK to leave as is? I thought the gist of Lance's response was this: It's ok to add vendor-specific columns to metadata ResultSets. However, the leading columns of the ResultSet must be the columns described in the JDBC spec and those columns must appear in the specified order. After that the order of vendor-specific columns doesn't matter. However, the names of those vendor-specific columns do matter; those names are the stable interface. I don't think the existing text on the compatibility webpage captures this. - Changes to Database Tables: We should be allowed to drop indexes on System tables. OK - Changes to Command Line Interfaces. I don't understand why error message text can't be changed. This contradicts what is said in the Interface Table below. Hm, good point. I suppose changing the error message text *is* an incompatible change, but given that the interface is private, it's OK to do it. But it is a confusing message. Any suggestions? I can (a) remove error message text from the list of incompatible changes (b) keep it, but clarify that this is a private interface (c) make error message text a public interface My vote is for (a). Anyone disagree? That's my vote too, thanks. - Other miscellaneous formats. I'm not clear on what these miscellaneou files and strings are. For example, I'd like to make sure that we're not enshrining the current RUNTIMESTATISTICS output. Again, I think this goes back to the same point. It's not clear what the relationship is to the classification of an interface in the interfaces table and what it means to make an incompatible change. I think you're assuming incompatible changes can only apply to public interfaces, because it's really kind of moot/inapplicable for private interfaces. I think there's value in describing what it means to make an incompatible interface change, but I think the ultimate "truth" in terms of what we actually support in terms of interface stability across releases is described in the interfaces table. I think some text in the "incompatible changes" section clarifying this would be helpful. Any thoughts? I can see that Private Stable applies to the client/server api. These apis should remain forward/backward compatible within a release family. Do Private Stable interfaces turn up in other situations? - Interface table: o Shouldn't the public client api be stable like the embedded api? Yes o What is meant by "Defaults returned by DatabaseMetadata methods"? I don't know, I think I put this in as feedback from someone else. Can anyone clarify? o I think that the format of RUNTIMESTATISTICS output is unstable. OK, anyone disagree? Thanks for your review, Rick! David David Van Couvering wrote: Hi, all. I am thinking of setting up two separate votes based on the Wiki page at http://wiki.apache.org/db-derby/ForwardCompatibility The first one would be on our overall model/approach to making compatibility commitments, as described in the Wiki page. The second would be specifically for the interface table, targetted at the 10.2 release. The reason for separating these out is because, for each release, we should update the interface table and have a new vote; the overall model/approach does not need to be updated or voted on for each release. I would copy the appropriate text directly into the email for the vote, so that the thing we're voting on is a frozen snapshot, not a live document like the Wiki page. I'd like your feedback on this approach. I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. Thanks, David
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Daniel John Debrunner <[EMAIL PROTECTED]> writes: > David Van Couvering wrote: >> Good news Lance, thanks, I was getting worried if we were going to have >> to regularly change column order and break existing applications/IDEs/etc. > > Hopefully we don't have any documented Derby specific additional columns > in the metadata, that would be non-standard. The only non-standard columns we have are METHOD_ID and PARAMETER_ID in getProcedureColumns and getFunctionParameters. For getProcedureColumns, they are documented in the reference manual. -- Knut Anders
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
David Van Couvering wrote: > Good news Lance, thanks, I was getting worried if we were going to have > to regularly change column order and break existing applications/IDEs/etc. Hopefully we don't have any documented Derby specific additional columns in the metadata, that would be non-standard. Dan. > > David > > Lance J. Andersen wrote: > >> hi guys >> >> Rick Hillegas wrote: >> >>> Hi David, >>> >>> I had a couple more comments on the compatibility commitments. >>> Cheers-Rick >>> >>> - Changes to stored procedures: We will have to change column order if >>> we add Derby-specific columns to a metadata ResultSet and then a later >>> JDBC also adds more columns. >> >> Any vendor specific columns added should only be accessed via column >> name and you should document that. >> >> we did clarify this in the JDBC spec > >
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Rick Hillegas wrote: Hi David, I had a couple more comments on the compatibility commitments. Cheers-Rick - Changes to stored procedures: We will have to change column order if we add Derby-specific columns to a metadata ResultSet and then a later JDBC also adds more columns. See Lance's email; OK to leave as is? - Changes to Database Tables: We should be allowed to drop indexes on System tables. OK - Changes to Command Line Interfaces. I don't understand why error message text can't be changed. This contradicts what is said in the Interface Table below. Hm, good point. I suppose changing the error message text *is* an incompatible change, but given that the interface is private, it's OK to do it. But it is a confusing message. Any suggestions? I can (a) remove error message text from the list of incompatible changes (b) keep it, but clarify that this is a private interface (c) make error message text a public interface My vote is for (a). Anyone disagree? - Other miscellaneous formats. I'm not clear on what these miscellaneou files and strings are. For example, I'd like to make sure that we're not enshrining the current RUNTIMESTATISTICS output. Again, I think this goes back to the same point. It's not clear what the relationship is to the classification of an interface in the interfaces table and what it means to make an incompatible change. I think you're assuming incompatible changes can only apply to public interfaces, because it's really kind of moot/inapplicable for private interfaces. I think there's value in describing what it means to make an incompatible interface change, but I think the ultimate "truth" in terms of what we actually support in terms of interface stability across releases is described in the interfaces table. I think some text in the "incompatible changes" section clarifying this would be helpful. Any thoughts? - Interface table: o Shouldn't the public client api be stable like the embedded api? Yes o What is meant by "Defaults returned by DatabaseMetadata methods"? I don't know, I think I put this in as feedback from someone else. Can anyone clarify? o I think that the format of RUNTIMESTATISTICS output is unstable. OK, anyone disagree? Thanks for your review, Rick! David David Van Couvering wrote: Hi, all. I am thinking of setting up two separate votes based on the Wiki page at http://wiki.apache.org/db-derby/ForwardCompatibility The first one would be on our overall model/approach to making compatibility commitments, as described in the Wiki page. The second would be specifically for the interface table, targetted at the 10.2 release. The reason for separating these out is because, for each release, we should update the interface table and have a new vote; the overall model/approach does not need to be updated or voted on for each release. I would copy the appropriate text directly into the email for the vote, so that the thing we're voting on is a frozen snapshot, not a live document like the Wiki page. I'd like your feedback on this approach. I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. Thanks, David
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Hi, Kathey, my silence (and I'm guessing the silence of others) was general approval of your comments. Did you update the page? I didn't see any change notifications fly by. My best attempt to answer your questions below: Kathey Marsden wrote: *Questions: *Under eprecated it says: Incompatible change allowed in minor rlease(x,Y) but then says it must continue to be supported until the next major release. The text that what happens at minor release boundaries is that it is deprecated. But could we clarify this? What kind of clarification are you looking for? I'm afraid I'm missing your point :( Thanks! David
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Good news Lance, thanks, I was getting worried if we were going to have to regularly change column order and break existing applications/IDEs/etc. David Lance J. Andersen wrote: hi guys Rick Hillegas wrote: Hi David, I had a couple more comments on the compatibility commitments. Cheers-Rick - Changes to stored procedures: We will have to change column order if we add Derby-specific columns to a metadata ResultSet and then a later JDBC also adds more columns. Any vendor specific columns added should only be accessed via column name and you should document that. we did clarify this in the JDBC spec
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
hi guys Rick Hillegas wrote: Hi David, I had a couple more comments on the compatibility commitments. Cheers-Rick - Changes to stored procedures: We will have to change column order if we add Derby-specific columns to a metadata ResultSet and then a later JDBC also adds more columns. Any vendor specific columns added should only be accessed via column name and you should document that. we did clarify this in the JDBC spec - Changes to Database Tables: We should be allowed to drop indexes on System tables. - Changes to Command Line Interfaces. I don't understand why error message text can't be changed. This contradicts what is said in the Interface Table below. - Other miscellaneous formats. I'm not clear on what these miscellaneou files and strings are. For example, I'd like to make sure that we're not enshrining the current RUNTIMESTATISTICS output. - Interface table: o Shouldn't the public client api be stable like the embedded api? o What is meant by "Defaults returned by DatabaseMetadata methods"? o I think that the format of RUNTIMESTATISTICS output is unstable. David Van Couvering wrote: Hi, all. I am thinking of setting up two separate votes based on the Wiki page at http://wiki.apache.org/db-derby/ForwardCompatibility The first one would be on our overall model/approach to making compatibility commitments, as described in the Wiki page. The second would be specifically for the interface table, targetted at the 10.2 release. The reason for separating these out is because, for each release, we should update the interface table and have a new vote; the overall model/approach does not need to be updated or voted on for each release. I would copy the appropriate text directly into the email for the vote, so that the thing we're voting on is a frozen snapshot, not a live document like the Wiki page. I'd like your feedback on this approach. I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. Thanks, David
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
Hi David, I had a couple more comments on the compatibility commitments. Cheers-Rick - Changes to stored procedures: We will have to change column order if we add Derby-specific columns to a metadata ResultSet and then a later JDBC also adds more columns. - Changes to Database Tables: We should be allowed to drop indexes on System tables. - Changes to Command Line Interfaces. I don't understand why error message text can't be changed. This contradicts what is said in the Interface Table below. - Other miscellaneous formats. I'm not clear on what these miscellaneou files and strings are. For example, I'd like to make sure that we're not enshrining the current RUNTIMESTATISTICS output. - Interface table: o Shouldn't the public client api be stable like the embedded api? o What is meant by "Defaults returned by DatabaseMetadata methods"? o I think that the format of RUNTIMESTATISTICS output is unstable. David Van Couvering wrote: Hi, all. I am thinking of setting up two separate votes based on the Wiki page at http://wiki.apache.org/db-derby/ForwardCompatibility The first one would be on our overall model/approach to making compatibility commitments, as described in the Wiki page. The second would be specifically for the interface table, targetted at the 10.2 release. The reason for separating these out is because, for each release, we should update the interface table and have a new vote; the overall model/approach does not need to be updated or voted on for each release. I would copy the appropriate text directly into the email for the vote, so that the thing we're voting on is a frozen snapshot, not a live document like the Wiki page. I'd like your feedback on this approach. I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. Thanks, David
Re: [PRE-VOTE DISCUSSION] Compatibility rules and interface table
David Van Couvering wrote: http://wiki.apache.org/db-derby/ForwardCompatibility [snip - stuff about 2 votes that sounds fine to me] I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. First of all, sorry for the huge delay in reviewing this. I would like to make the following edits to the page before vote. If I don't hear by end of day today I will go ahead and make them. Nothing controversial I hope. Goal - Remove the alternate goal I think the goal as stated and the stated "Exceptions" section are clear as is. Exceptions Add that the Jira "Existing application Impact" and "Release Note Needed" checkbox should be be used to indicate such changes have been made and the standard ReleaseNoteFormat should be used to describe possible impact. Note that intentional changes that might affect existing applicaitons should be deferred to minor release boundaries if at all possible. Critical bugs such as corruption and wrong results may require change in a maintenance release. I think the Vote that client should match embedded behaviour in the "Other Notes" section should be moved up here. Changes to Database Tables Changes to system tables cannot occur for soft upgrade. Associated upgrade code and tests will be added for compatible changes. Incompatible Changes for Data File Formats I won't change this but seems like it should be filled in. In general it seems to me not the data file import but its impact on soft/hard upgrade is key here. Changes to Network Protocol add Compatiblie Change Add unimplemented DRDA support to client or server with appropriate logic to trigger it only for Derby versions that support it. Incompatible Change: Add unimplemented DRDA Support to client or server that might impact earlier releases of client or server. Other Notes I would like to rename "Other Notes" to "JVM Support and Version Interoperability" Questions: Under eprecated it says: Incompatible change allowed in minor rlease(x,Y) but then says it must continue to be supported until the next major release. The text that what happens at minor release boundaries is that it is deprecated. But could we clarify this?
[PRE-VOTE DISCUSSION] Compatibility rules and interface table
Hi, all. I am thinking of setting up two separate votes based on the Wiki page at http://wiki.apache.org/db-derby/ForwardCompatibility The first one would be on our overall model/approach to making compatibility commitments, as described in the Wiki page. The second would be specifically for the interface table, targetted at the 10.2 release. The reason for separating these out is because, for each release, we should update the interface table and have a new vote; the overall model/approach does not need to be updated or voted on for each release. I would copy the appropriate text directly into the email for the vote, so that the thing we're voting on is a frozen snapshot, not a live document like the Wiki page. I'd like your feedback on this approach. I'd also like to make sure there aren't any lingering issues with the Wiki page as it stands, before I go through the process of running a vote. Thanks, David
