Writing Shared Libraries, first draft

[Mike Hearn]

Hi guys,

The GNOME HIG has proven useful for increasing the usability of open
source applications, even for apps that aren't actually GNOME programs.
By providing best practice guidance and training materials for
developers, it helps our community develop better software.

I thought I'd try writing an equivalent for library developers. This
document gathers together generally accepted best practices and sticks
them all in one document complete with examples. Here it is:

http://navi.cx/~mike/writing-shared-libraries.html

There are a few controversial points in it (well duh, the HIG is/was
controversial too :)

- The parts on backwards compatibility and semantic interfaces may prove
  new to some people. Like any guide, you are free to ignore any part if
  you can justify it :)
- The restricted form of symbol versioning described is not widely used
  so it's hardly a best practice, but is generally accepted as being a
  good plan on platforms that support it
- Some people don't like the idea that software/package version should
  equal interface version. I do not know why.
- As far as I know, no library today actually implements all of the 
  recommendations given here so you can't really call it a best
  practices document. Oh well :)

I'd appreciate comments. I have already been told the part on applying
symbol versions is a bit confusing, I will try and clarify it later.

If people think it's good, I'd like to stick it on the freedesktop.org
Wiki and start pointing people towards it.

thanks -mike