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"
<[EMAIL PROTECTED]> 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"
<[EMAIL PROTECTED]> 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
