API documentation requirements for next releases

[Federico Mena Quintero <federico ximian com>]

[Argh, hit "Send" too soon, sorry about that.  Let's try again.]

Hi,

Some time ago we discussed adding a requirement for new APIs that enter
the core platform [1]:  those modules which add new APIs must provide
documentation for those APIs.  Thanks to Murray for bringing it up, and
for resurrecting the discussion.

The release team has decided that we'll try this plan for the 2.14
release.  If it works out well, we'll use it for subsequent releases as
well.  You can see the details here:

	http://live.gnome.org/ReleasePlanning/NewApiDocs

Summary:

For modules in the core platform [2], we'll require that new APIs and
other public interfaces have documentation.  This includes C functions,
configuration files, GConf keys, and anything that is not internal only.

     1. Document any new public interfaces since the last stable version
        of the module (e.g. the jump from 2.12.x to 2.14.0). You can do
        this with gtk-doc.
     2. Mark any newly deprecated interfaces as such.
     3. Any new module proposed for the platform must be fully
        documented.

In each release cycle, the deadline for API documentation of new API is
one week after API freeze.  Lack of compliance will be treated the same
as freeze breaks. 

For this release cycle, API freeze is on 2006/Jan/16.  So, the deadline
for API documentation will be on 2006/Jan/23.

While this involves a little more work for maintainers, it will keep us
honest as a platform.  It will also ensure that we gradually move toward
full coverage of our documentation.

[1] http://mail.gnome.org/archives/desktop-devel-list/2005-November/msg00216.html

[2] http://live.gnome.org/TwoPointThirteen/Platform

Thanks,

  Federico