GNOME API/ABI Stability document 90% done – help needed

Last year at GUADEC I promised to help the SUN people make their (lengthily vague) API/ABI stability documentation requirements meet up with GNOME’s API/ABI stability practices, so everyone can learn about the good stuff that we do, and so we can recommend some minor improvements. We almost got there.

But the draft document is still not quite ready. The main issue is the library versioning section. I’ve listed some of my confusion there. As far as I know, GTK+ just doesn’t use it because it’s more trouble than it’s worth. When I’ve tried to follow the instructions for using it in the past, I’ve caused ABI problems when I just wanted to say “here’s some new ABI that doesn’t break the old ABI.”. So I’d like either a knowledgeable explanation of why it should be ignored, or clear examples of how to use it. Feel free to fill up the comments with clues.

The next GUADEC is upon us, and a year seems too long to get this done.