GNOME Bugzilla – Bug 170860
gtk-doc should have definitions for stability
Last modified: 2014-02-17 20:58:49 UTC
Now gtk-doc supports the ability to specify stability levels for each interface and supports the stability levels of "Stable", "Unstable" and "Private". The definitions were discussed on the gtk-doc-list@gnome.org. Refer here: http://mail.gnome.org/archives/gtk-doc-list/2005-January/msg00001.html It isn't reasonable to expect people to find the definitions in the mail archives, so these definitions should be included somewhere where people can view them and understand what each level means. The generated gtk-docs should also be enhanced so that instead of simply saying "Stable", "Unstable" and "Private", these are links that point to the definitions. The definitions are: + Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications. + Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next. The Unstable interface level is a warning that these interfaces are subject to change without warning and should not be used in unbundled products. Given such caveats, customer impact need not be a factor when considering incompatible changes to an Unstable interface in a major or minor release. Nonetheless, when such changes are introduced, the changes should still be mentioned in the release notes for the affected release. + Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways. + Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal. This level is not intended to be documented via gtk-doc.
You need to add a new section to glib/docs/reference/glib/glib-docs.sgml, possibly just after the "&glib-Resources;" section. To identify the version description as a link target I think you can do: <anchor id="GTK-DOC-VERSION-PUBLIC"/> To link from the version symbol to the description I think you can do: <link linkend=\"GTK-DOC-VERSION-PUBLIC\">PUBLIC</link> I'm not 100% sure the above will work though.
I don't think that Glib is the appropriate place for this. I would prefer to have a standalone document (kind of user-manual for reading gtk-doc manuals). What can we put in there: * stability (obviously) * whats means deprecated and sice for the developer Anything else? I volunteer to write that document and add the autofoo stuff so that it gets installed. I would change the gtkdoc.make to automatically run gtkdoc-fixxref against this document.
What do we do about this?
Since I originally implemented the feature to add stability levels to gtk-doc style documentation, I wanted to comment. In adding the ability to specify stability levels in gtk-doc, my hope is that modules would make use of this feature so that the installed GTK+ docs would provide more information about which interfaces people should depend upon. This would help to clarify which libraries are intended for end-use and which are intended for more private use within the GNOME stack itself. By private use, I mean those modules which don't mind having interfaces break on each minor GNOME release since those modules are being updated for each minor release anyway (e.g. modules that depend on libegg). In other words, it might make sense for those libraries that are in the Platform (and not expected to be deprecated) to have a clear stability levels saying "use me". Libraries that developers outside of the GNOME community shouldn't depend upon (because they are expected to change each GNOME minor release) could more clearly be marked as being unstable or "don't use me unless you are comfortable with the instability". However, it doesn't seem that the GNOME community has really adopted these ideas, and I don't think any modules are yet marking their interfaces with gtk-doc stability levels. Even still, this functionality is nice to have and I'd think it would be good to encourage the GNOME community to be more clear about this. Perhaps people would use it more if it were more clearly documented and the stability levels had more clear definitions (as proposed). On the other hand, if people wanted to rip this functionality out since it is not being used, then I would understand.
There is also http://bugzilla.gnome.org/show_bug.cgi?id=166363 and then we have since and deprecated. I could actually also convert process the manual with gtk-doc and install it. All docs could be gtkdoc-fixxreffed automatically against this one, so that those terms are links to the explanation.
Hey Stefan, you've set this bug to NEEDINFO in comment #3. As I think, the question has been answered, I am reopening. Feel free to accept this issue as a bug and set to NEW or close as WONTFIX.
Tobias, this bug was NEEDINFO as I was asking for a design how this should be solved. Even though I am maintaienr of gtk-doc I can come up with all ready made designs for all kind of things. Brian stated that he has no solution for this. Still NEEDINFO is the right status for me, as ther eis not enough info to actualy solve the issue. Generally, I am looking at the gtk-doc bugs. There is no need to triage the bugs that are in the right product already. I appreciate you work, but please leave the bug status to the maintainers.
Dear Stefan, sorry for my late answer. Of course, you can't come up with all designs yourself. Most of the time, the bugreporter can't either. Most bugzilla users set a bug to NEEDINFO if it's not yet clear whether a filed issue is a bug which needs to be fixed. If it is identified as such, people usually set the bug to "NEW" so that someone with spare time can have a look at things which need to be done. In the best case they'll assign it to themselves then. If an issue turns out to be no bug, either because it's simply not the modules fault or based on the given information one can't say that it's fixable, it's closed as INCOMPLETE most of the time. Having that said, NEEDINFO doesn't, at least for the bugsquad, exactly reflect that you're taking this issue as a bug and are still thinking about it. Also, bugsquad is having a look at bugs which seem to have unjustified NEEDINFO flag. Either because the requested information has been provided or a reasonable timeframe is exceeded. Bugsquad considers 3-6 month for a reasonable timeframe. This has been exceeded in this bug, because no new information has been added since then. Anway, a bug set to NEEDINFO for a long time doesn't reflect that it's being cared of ;-) A good approach to have bugsquad not fiddle around with your bugs, is to set the status-whiteboard to something like "Dear bugsquad, please let this bug remain NEEDINFO" Some modules indeed request that bugsquad doesn't do anything with their bugs, see http://live.gnome.org/Bugsquad/TriageGuide/ProductSpecificGuidelines, but at least I can't promise to have that in mind everytime, so please bear with me.
> find . -name "*.c" -exec grep -Hn "Stability: " {} \; | cut -d'/' -f2 | sort -u clutter gobject-introspection gssdp gupnp gupnp-av libsecret Now that these are actually used, we could do like we do for the gobject-introspection and emit blobs into the glossary.
commit 90713c99566e1bc51597a44cceb270c4ba84c8cf Author: Stefan Sauer <ensonic@users.sf.net> Date: Mon Feb 17 21:56:52 2014 +0100 mkdb: add glossary entries for stability levels Add the definitions for stabiloity levels to the glossary. Fixes #170860