db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <de...@mylevita.com>
Subject Re: Should we vote on it? (was Re: Discussion (in preparation for a vote) on interface stability table)
Date Sat, 01 Apr 2006 02:59:40 GMT
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
> >>>
> >>>
> >>
> > 
> 


Mime
View raw message