I have not bothered very much with the change documentation. I have
thought that it is the steady state documentation that is the important
one. Maybe that is my problem.
I have thought that the changelog in the cookbook, the @deprecated and
@since statements in the code, the commit log messages, and the issue
log would be enough change documentation. I understand that it might be
a little hard to get a good overview.
Can't we use the changelog in the Cookbook for big changes and the
@since and @deprecated statements in the code for detailed changes? Do
we really need something in between?
/Linus
> -----Original Message-----
> From: Tom Morris [mailto:[EMAIL PROTECTED]
> Sent: den 11 augusti 2006 19:50
> To: [email protected]
> Subject: RE: [argouml-dev] API compatibility (again)
>
> I think Bob was asking about the change documentation, not the steady
> state
> documentation.
>
> I've suggested in the past that we start the release notes at the
> beginning
> of the release cycle and have developers update them as they implement
> significant new features or make significant changes. Creating the
> release
> notes during the release cycle rather than at the end has the
advantage
> that
> things are less likely to get forgotten (if the developers are
> conscientious
> about updating the document).
>
> Certainly as a plug-in developer I'd appreciate (expect even) an
explicit
> list of newly deprecated or removed methods and classes. As a user,
I'd
> appreciate a brief description of new and changed features. One could
> argue
> that much, although not all, of this information is available in the
issue
> database if you dig hard enough, but it's not in a user friendly
format.
>
> Another possibility instead of version specific release notes would be
to
> maintain a continuous "What's New" document. These are both pretty
> standard
> and well known mechanism for conveying this type of information to
users
> and
> developers.
>
> Tom
>
> > -----Original Message-----
> > From: Linus Tolke [mailto:[EMAIL PROTECTED]
> > Sent: Friday, August 11, 2006 12:09 PM
> > To: [email protected]
> > Subject: RE: [argouml-dev] API compatibility (again)
> >
> >
> > On where to document the API.
> >
> > Bob Tarling wrote:
> > ...
> > > Should we keep some document for this in CVS to update as
required.
> >
> > My answer is, yes.
> >
> > Firstly it should be documented in the java classes by having
> > the API methods public/protected and the API classes and
> > interfaces public while the non-API methods should be default
> > or private. This will be generated
> > (nightly) into the API-version of the javadoc. This will make
> > sure that the code is always consistent with the
> > documentation since it is the same.
> >
> > If there are needs for any specific discussions it should
> > also be documented in the Cookbook, chapter 5 in the correct
> > section for the subsystem providing the API.
> >
> > /Linus
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
