gir stability

[Ryan Lortie <desrt desrt ca>]

It seems like we've been avoiding talking about this particular issue
for a while, but I think it's time we got a bit more serious about it.

  https://bugzilla.gnome.org/show_bug.cgi?id=657385

This bug introduced a 'Rename to:' field on gtk_menu_popup_for_device(),
which of course, is an API change of sorts.  We've all made (or ACKed)
changes like this in the past so there's not a lot of blame to assign
here (other than to all of us).

What makes this particular incident of note is that popup_for_device()
existed in Gtk 3.2 and was bound as such.  Python applications[1]
started using it, and then, with this commit, it disappeared.

We need to figure out what our story is with respect to annotations.
'Rename to:' is an extreme example (since an entire function, as named,
disappears) but we can easily cause problems just as serious with
changes that look a lot more innocent (like changing array length
parameters or such).  We can even break vala bindings with the
introduction of an (allow none).

On one extreme, do we say that we don't care about providing a stable
API to users of our bindings at all?  On the other hand, do we go as far
as to guarantee bugs-compatible behaviour between our stable releases of
introspection bindings?

It's pretty clear that we can't continue along ignoring the issue as we
have been so far...

Cheers