Modules in this release set should follow these rules. Note that modules that are not in the Platform release set, such as modules in the Desktop release set, are not required to follow these rules.
The API must be frozen on the scheduled API freeze date. Between the freeze date and the final date, permission for an APch I freeze-break may be requested from the release team.
The API and ABI must be completely frozen on the scheduled final release date. You may not break this API/ABI freeze ever, but you may add API during the next development schedule.
Major versions of GNOME may provide parallel-installable APIs, which allow the API to be changed without breaking existing applications, because they actually provide a completely new API/ABI. For instance, the GNOME 2.x Developer Platform can be installed without affecting the older GNOME 1.2 Developer Platform or applications which use it. However, these major changes do not happen often, so make sure your API is built to last.
The meaning of API/ABI freeze
API means Application Programming Interface - it is what a compiler uses to build your application. ABI means Application Binary Interface - it is what an application uses at runtime. Here we assume that the API/ABI is provided by shared C libraries and/or C header files.
- Do not break ABI. For instance, if an application uses 2.6.0, installing 2.6.1 should not intentionally break that already-installed application.
- Do not break API. For instance, you should not break application builds. If an application built with 2.6.0, then it should build with 2.6.1.
You may not add API in the stable (2.6.x, for instance) phase. You must wait until the next schedule to add API. This means that there are not multiple versions of the API, so it is simpler for developers to aim at a particular API version. Remember, it's not a problem if you must wait to add API, because you must only wait <6 months until the next stable release. For instance, GTK+ 2.4 adds API compared to GTK+ 2.2.
During the unstable development phase (before the API/ABI Freeze), you should use odd numbers for your tarball version numbers, and for any installed libraries. For the stable phase you will use even numbers, beginning with the first stable release. For instance, gtk+-2.3.x.tar.gz tarballs are unstable, but gtk+-2.4.x.tar.gz tarballs are stable. Do not change these major.minor versions during a stable phase.
Try to use version numbers that match the GNOME version number. For instance, GNOME 2.7.1 might have libgnomeui-2.7.1 and gnome-vfs-2.7.1. Not all modules must do this.
Documentation requirements for new APIs
We have a fair number of modules or libraries that are part of the core GNOME platform (glib, pango, gtk+, d-bus, etc.). However, not all of those modules have a tradition of ensuring that new public interfaces (APIs, configuration files, GConf keys) get documented. Since no maintainer objected to the proposal on desktop-devel-list (except for Mark who later withdrew his objection), this is now becoming part of the requirements of the platform module release set.
You can see the original proposal that Murray Cumming sent to desktop-devel-list.
The following requirements apply to the Platform release set:
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. People on gtk-doc-list or desktop-devel-list can help you set up this infrastructure. Your docs should say the version number in which each interface was added; please see the Howto section below for the details.
Mark any newly deprecated interfaces as such. Please see the Howto section below for the details.
Any new module proposed for the platform must be fully documented.
- If you did not add new public interfaces or deprecate any interfaces (or even if you did and want to go the extra mile), take some of the existing undocumented interfaces and write docs for them. This ensures that we will eventually reach the goal of having documentation for all the public interfaces.
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.
Please read the gtk-doc manual for a full explanation of the syntax.
Make sure you use the "Since:" section in your gtk-doc comments. For example,
/** * foo_widget_add_foam: * @foo: a #FooWidget * @foam_type: Type of foam to add to #FooWidget. FOAM_COARSE will produce * the fastest results, but they won't be very tasty. FOAM_SUPERFINE will produce * the tastiest results, but it will take longer. * * Adds foam on top of a #FooWidget. Different types of foam require * different preparation times. * * Since: 2.14 * * See also: foo_widget_sprinkle_condiment() */ void foo_widget_add_foam (FooWidget *foo, FoamType foam_type)
Please use the "Deprecated:" tag in your gtk-doc comments to indicate when an interface was deprecated, and also mention what the programmer should use instead. For example:
/** * foo_widget_add_cinnamon: * @foo: a #FooWidget * * Adds cinnamon on top of a #FooWidget. * * Deprecated: 2.14: Please use foo_widget_sprinkle_condiment() instead, * as this function is more generic. */ void foo_widget_add_cinnamon (FooWidget *widget)
Define an alias to an xrefitem in your Doxygen file. For instance, ALIASES += "newin2p8=\xrefitem newin2p8s \"Since gtkmm 2.8\" \"New API in gtkmm 2.8\" "\n""
Then use that new tag in your documentation:
/** Adds foam on top of the widget. Different types of foam require * different preparation times. * * @param foam_type The type of foam to add to the widget. FOAM_COARSE will produce * the fastest results, but they won't be very tasty. FOAM_SUPERFINE will produce * the tastiest results, but it will take longer. * * @newin2p8 * * @see Foo::Widget::sprinkle_condiment() */ void add_foam(FoamType foam_type = FOAM_SUPERFINE);
Doxygen already has a @since tag, but it does not generate lists, or really understand version numbers. Feel free to make doxygen do this.
Please use the "@deprecated" tag in your documentation to indicate when an interface was deprecated, and also mention what the programmer should use instead. For example:
/** Adds cinnamon on top of the widget. * * @deprecated This function is obsolete since 2.14. Please * use sprinkle_condiment() instead, as this function * is more generic. */ void add_cinnamon();