Re: ARC & GNOME [Was: How we make decisions...]

[Sean Middleditch <elanthis awesomeplay com>]

On Tue, 2004-12-07 at 15:55 -0600, Brian Cameron wrote:
> Mike:
> 
> > On Tue, 07 Dec 2004 14:09:46 -0600, Brian Cameron wrote:
> > 
> >>I would also be very interested in dedicating time to improve the
> >>overall developer documentation found on developer.gnome.org. 
> > 
> > OK, just to clarify Sean and I weren't talking about API reference docs,
> > more documentation on what libraries made breaking changes at which points
> > so ISVs can get information relevant to backwards compatibility. It's a
> > slight tangent to the API docs discussion :)
> 
> Right.  I did catch that, but I am also interested in working to generally
> improve the developer documentation in GNOME, and not just API reference
> docs.  In other words, getting better documentation about interface change
> in libraries and applications from release-to-release would be very useful
> to me.

One of my goals with such a sight would be not only to document such
changes but serve as a center for education and collaboration to help
_avoid_ such breaks.  Documenting breaks might help developers to a
small extent, but whether a break is documented or not the users are
still screwed over due to apathy or carelessness.

Of particular irritation is when packagers take a library that is
perfectly versioned and otherwise developed sanely and make a package
that isn't.  Take Fedora Core and its curl package, for example.  They
have a single package that holds the latest major ABI/API version of
libcurl and curl.  So if you have App A that uses libcurl.so.2 and App B
that uses libcurl.so.3, you are completely screwed.  You can't even
(easily) do a manual rpm -i install of both versions because both
packages also include the curl command line utility.  This is a perfect
example of a library with proper versioning that packagers break, and
that's avoidable.  (For what it's worth, yes I did file a bug on Fedora
for this, although it has, after several months, still not even seen a
reply.)

> 
> However, I think that the gtk-doc tool might be a good place to document
> library breakages.  Currently the gtk-doc tool doesn't provide the ability
> to put comments in the code to highlight when interfaces change (when
> structures change, when file-integration points change, when interaction
> with environment variables change, when enumerations change, etc.).
> Currently the only thing gtk-doc provides that is in this arena is
> information about what release new function interfaces were added.
> 
> If gtk-doc were enhanced to provide more information about interface change,
> then this might be a good way to document such change.  gtk-doc could
> certainly be enhanced to provide good information about what interface
> changes happened from release-to-release.

If gtk-doc can notice interface change information, the tools should be
modified to raise utter hell when the interface *does* change, because
it shouldn't.  Ever.  Not until the 3.0 series.

I would like to see a general-purpose (and preferably cross-language
where possible) tool for generating an ABI description for a library and
allowing comparisons between two versions.  So during release you could
save a copy of the ABI definition, and during development you could
generate snapshots and compare it with the last release's version.  The
tool could then let you know whether ABI is broken (major version bump),
extended (minor version bump), or identical (revision or no version
bump).  The same tool could perhaps also be used for symbol table
generations for ELF libraries.

> 
> This would require enhancing gtk-doc to support new comment tags in the
> source code, and probably enhancing gtk-doc to provide some additional
> reports to highlight diffs from one release to the next.  But this is
> probably a better way to document change than trying to keep such
> documentation separate from the code, I'd think.  Also it just seems
> more sensible to leveridge the existing tools that generate good docs
> from the code so that it provides more information about change.
>