What are the ELF shared lib symbol versioning best practices?

[David Howells]

Is there a good description of ELF shared library symbol versioning best
practices somewhere?

In particular, under what conditions do you need to create a new section in
the versioning file given to the linker's --version-script option when new
symbols are added?

And what do you do if you've done it wrong?

For example, in libkeyutils, I added a couple of symbols to KEYUTILS_1.4 when
I should perhaps have created KEYUTILS_1.5 and added them there:

	http://git.kernel.org/cgit/linux/kernel/git/dhowells/keyutils.git/commit/?id=49249ce7d84a967fcdc06fbe6bf1d0cf89ac5215

I have been given a patch to move these symbols to KEYUTILS_1.5, but checking
the keyctl program with "readelf -s", I see:

    47: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND recursive_session_key_sca at KEYUTILS_1.4 (7)

so I would guess applying this patch would break anything that uses this.

I assumed that adding them to KEYUTILS_1.4 would be okay because nothing
would've tried to use them previously because they didn't exist in any
version.

David