Sorry, I meant to say libbonoboui has version 0.0.0 not 4.0.0.  They both should
either be bumped to 1.0.0 or 0.1.0 is what I should have said.

Dudie - they should never be bumped - we can't change the major .so number -
that'd break everything linking to it, shaft the ABI garentees we made etc. etc.
ie. what are you smoking ? :-)

Furthermore the above list is not that useful to me, can you answer:
    + what is the datum you're comparing from and to what - which versions
      are you using ?
        + is that a meaningful or realistic thing to do ?
        + presumably a more interesting list would come from the last
          version any of us shipped & made garentees about.
    + which of these functions are actually public & defined in the headers
      - rather than just happenning (due to bad symbol exporting discipline)
      to be exported ?
        + [ I'm sorry but if you use random internal symbols that are not 
            declared in headers you have bad things coming to you whatever ]

I'm not sure what you're trying to achieve here really.

As I said, if the interfaces removed were private interfaces, then only the
minor number should be bumped.  If the interfaces removed were public
interfaces, then there was ABI breakage.  I suspect that they were private
functions since nobody has complained about them, but research will be
necessary.  At the very least since functions were added the minor number should
be bumped.

I was testing version 2.4.3 which was included in GNOME 2.0 with version 2.12.2
included in GNOME 2.10.  You are right that ABI rules only apply since ORBit2
was introduced into the platform.  I can't find any information anywhere about
when modules were introduced into the Platform, so I've been assuming it was
added since GNOME 2.0.  If that's wrong, let me know and I'll rerun the tests.

Looking at the 2.0 source code for bonobo, it seems that bonobo_init is in the
bonobo-shutdown.h header file and the others seem to be in
bonobo-running-context.h.  These are listed as noninst_HEADERS in the
Makefile.am file, so these are private symbols.

Looking at the 2.0 source code for bonoboui, bonobo_dock_band_handle_key_nav and
 bonobo_dock_handle_key_nav is in bonobo-dock-band.h,
bonobo_ui_toolbar_control_item_set_sensitive and bonobo_widget_clobber_focus is
in bonobo-ui-private.h, and bonobo_ui_toolbar_seperator* is in
bonobo-ui-toolbar-separator-item.h.  Looking at Makefile.am, bonobo-ui-private
and bonobo-ui-toolbar-separator-item are in noinst_HEADER.  However,
bonobo-dock-band.h seems to be an exposed header file.  Looking at that header
file, these interfaces are surrounded by #ifdef BONOB_UI_INTERNAL.

Good deal, this means we just need to bump the minor number for these two libraries.

So, we need to bump this one:

LIBBONOBO_LT_VERSION_INFO='-version-info 0:0:0'

to what? 0:0:1?

no idea - we should read the libtool man page; the versioning is (AFAIR) tangled beyond belief and ugly in the extreme.

As long as we don't bump the major version & break ABI compat, I'm happy with whatever.

From the libtool docs:

   This flag accepts an argument of the form
`CURRENT[:REVISION[:AGE]]'.  So, passing `-version-info 3:12:1' sets
CURRENT to 3, REVISION to 12, and AGE to 1.

...

 5. If any interfaces have been added since the last public release,
     then increment AGE.

I guess 0:0:1 is it then. Brian, you agree that this is what you're after?

To be honest, I'm not sure what really should be done here - I opened the bug so I should comment. 

Sun's ARC (Architecture Review Committee, responsible for interface stability risk management at Sun) committee reviewed this concern about updating the version numbers and determined that (at least on Solaris), incrementing library version numbers does not add any interface stability value.

I originally reported this bug because the GNOME release team website seems to encourage its use, and the process didn't seem to be followed for these modules.  At first, I assumed that this is supposed to be done for interface stability - but perhaps it is more libtool specific (like make it less likely that your module will have weird libtool problems when you try to build it),

http://live.gnome.org/MaintainersCorner/Releasing

I'm not sure why the release team recommends this, or why the libtool documentation suggests that it is good to do this.  But, assuming that it adds some value, bumping the number so that we follow the libtool and GNOME release team process is probably easier than changing the release team process.  :)

Though perhaps the recommendation should be removed from the GNOME Release Team website if it doesn't really add value - especially if GNOME Platform module maintainers don't see the value in it.

Brian - glad you don't think breaking ABI compat by changing the major .so version is a great idea any more :-)

Wrt. the other things - sure, you can try to unwind the mind-mangled section that you link to there:

# The string is of the form C:R:A.
# - If interfaces have been changed or added, but binary compatibility has
#   been preserved, change to C+1:0:A+1
# - If binary compatibility has been broken (eg removed or changed interfaces)
#   change to C+1:0:0
# - If the interface is the same as the previous version, change to C:R+1:A

But that scares the living daylights out of me - and (in no way) can be considered easy to use, comprehensible, or even a useful representation of what has happened (surely ?). It seems in the common case: adding interfaces compatibly, you have to (randomly) increment 2 numbers in lock-step - not intuitive, not something memorable; and if you screw it up - all hell breaks loose.

Basically until libtool comes up with a clear and comprehensible way of versioning things, I'd rather just stuck with no .so number change [ in the past it has served us well ]; and let anyone that -really- cares about precise versioning stuff do dlsym tricks with symbols :-)

From my reading of the libtool info page incrementing age should be enough when there's only been additions? Maybe the release team page is wrong somehow?

Yes, I suspect that this is a bug in the release process.  I'm changing the bug category to "Release Engineering' so perhaps we'll get some ideas from them.  
If they think this rule is important enough to follow, then we probably should 
do something about it.  libbonobo and libbonoboui are just two of many GNOME 
Platform libraries (let alone desktop ones) that is not following this 
recommendation.

Note that there was some email discussion about this topic on
release-team@gnome.org, and it sort of seemed that people didn't see the value 
in this then.

http://mail.gnome.org/archives/release-team/2005-August/msg00252.html

However, I notice that when the release team migrated their "For Maintainers" section to the Wiki, that they kept this information about as the recommendation.
Though I suspect that the release team website just needs some attention.  The
website is missing a number of "Best Practices" that are generally followed by the community.  For example:

+ The For Maintainers page doesn't seem to explain that the release team 
  recently agreed that all Platform module maintainers are responsible for
  making sure the gtk-doc generated documentation is up-to-date, or how
  the Since: and Deprecated: tags should be used.

+ The Release team website doesn't really explain what the ABI Stabiity
  guarantee for GNOME Platform libraries means for end-users, third party
  integrators, etc.  

+ Although the community does seem to manage issues relating to ABI
  compatibility reasonably, there is no information on the website about
  what people are supposed to do when they identify breakage (who to 
  contact, how to file a bug and fill the fields properly to get
  proper attention), and how the community tends to respond to issues
  when raised.

+ Although the release team website does explain what the Platform 
  libraries are fairly well, it doesn't explain what the process is
  for making a module a part of the Platform, or the process we use
  for adding new modules to the GNOME desktop.  Probably should 
  explain some things like what a maintainer should consider 
  before proposing their module (e.g. that their documentation meets
  requirements, etc.) for the Platform, and how to actually go about
  proposing it.  Nor does it explain the process we use for proposing
  new Desktop modules.

+ There doesn't seem to be much information about how FreeDesktop 
  specifications work in the GNOME desktop.  It seems it would be
  useful if somewhere we documented which specs are supported and
  what GNOME version they were introduced into.  There are probably
  other external interfaces (such as Xorg extensions) that would
  also be good to document like this.

I think the GNOME community would benefit if our release process were
better documented.  Most of what we decide is done in public forums,
but because the process isn't well documented it is hard for people
to get involved and understand how things are done.  Also, I think
people often complain that people send mail to the wrong alias, or
send emails that aren't fully thought through.  I think better
process documentation would help in these regards.

Some information is here that might be useful to more integrate with
the release engineering website.  I think it would be better to provide
more detail about interface stability in the GNOME Platform.

http://live.gnome.org/InterfaceSpecification/InterfaceTable?highlight=%28interfacespecification%29

(In reply to comment #8)
> Wrt. the other things - sure, you can try to unwind the mind-mangled section
> that you link to there:
> 
> # The string is of the form C:R:A.
> # - If interfaces have been changed or added, but binary compatibility has
> #   been preserved, change to C+1:0:A+1
> # - If binary compatibility has been broken (eg removed or changed interfaces)
> #   change to C+1:0:0
> # - If the interface is the same as the previous version, change to C:R+1:A
> 
> But that scares the living daylights out of me - and (in no way) can be
> considered easy to use, comprehensible, or even a useful representation of what
> has happened (surely ?). It seems in the common case: adding interfaces
> compatibly, you have to (randomly) increment 2 numbers in lock-step - not
> intuitive, not something memorable; and if you screw it up - all hell breaks
> loose.

All GNOME libraries I've been working on are using this, and really, after a while, you get used to it. If you get it wrong, don't worry, packagers will slap you :-)

Kjartan's comment is interesting. We need to look at this.

I assume this is obsolete nowadays.