Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Mon, 03 Apr 2006 09:54:41 -0700
From: "David W. Van Couvering" <David.Vancouvering@Sun.COM>
Subject: Re: Should we vote on it? (was Re: Discussion (in preparation for a
 vote) on interface stability table)
In-reply-to: <20060401025940.19532.qmail@web81606.mail.mud.yahoo.com>
To: derby-dev@db.apache.org
Message-id: <44315351.1000805@sun.com>
MIME-version: 1.0
Content-type: text/plain; charset=ISO-8859-1; format=flowed
Content-transfer-encoding: 7BIT
User-Agent: Mozilla Thunderbird 1.0.7 (Windows/20050923)
References: <20060401025940.19532.qmail@web81606.mail.mud.yahoo.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"
> <David.Vancouvering@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"
>>><David.Vancouvering@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
>>>>>
>>>>>
>>>>
>