Policy §8.5 currently says that "If there are development files
associated with a shared library, the source package needs to generate a
binary development package named {libraryname}-dev, or if you need to
support multiple development versions at a time,
{libraryname}{apiversion}-dev", leaving it up to the package maintainer
whether to use the API version or not.

Following recent discussion in the GNOME team about whether -dev package
names should usually look like libfoo-dev or like libfoo-2-dev, I think
it would be better for Policy to provide more specific guidance here. I
don't yet have concrete wording to propose for this.

Broadly, there are two kinds of library here: parallel-installable[1]
and not parallel-installable, and I think we should have different
policies for them.

For a parallel-installable library, the "name" that is used by the API
consumer actually looks more like a (name, major version) pair. For
example, to use SDL 3, a developer is expected to use `pkgconf --cflags
--libs sdl3` or `gcc -lSDL3` or Meson `dependency("sdl3")` or CMake 
`find_package("SDL3")`. There are lots of other good examples of these
libraries in the GNOME ecosystem, such as glib-2.0, libgtk-4 and
libadwaita-1. Upstreams do this to make sure that if they need more than
one major version of the API at a time with dependent projects being
ported from one to another, as SDL and GTK have done, they will be able
to do so without needing a flag-day.

For a non-parallel-installable library, the name that is used by the API
consumer is just a name. For example, to use fontconfig, a developer is
expected to use `pkgconf --cflags --libs fontconfig` or `gcc
-lfontconfig`, or to use libjpeg(-turbo), a developer is expected to use 
`pkgconf ...  libjpeg` or `gcc -ljpeg`. zlib, util-linux's libraries,
and systemd's libraries are other good sources of examples. Upstreams
do this if they don't expect to break API frequently (ideally never).

Some libraries are, unfortunately, an awkward mixture of these. For
example, to use libtiff, a developer whose build system is based on
pkgconf is expected to use `pkgconf --cflags --libs libtiff-4`, but a
developer not using pkgconf is expected to use `-ltiff`. Ideally we
should ask upstreams to avoid this, and instead ask them to choose one
consistent policy: either the library is fully parallel-installable like
SDL, or fully non-parallel-installable like fontconfig.

In all cases, we don't want the -dev package to change its name for no
reason if the API is still broadly compatible with what came before, so
it shouldn't include the ABI major version ("SOVERSION") as seen in the
SONAME. For example, it's correct that the 1 of libfontconfig.so.1
appears in the runtime library package name but not in the -dev package
name. The -dev package name should usually only change if there's a new,
parallel-installable version, like the jump from SDL 2 to 3.

I think the Policy recommendation here should be:

* For new libraries, make the name of the -dev package reflect the
  name(s) that a dependent package would request in their build system.
  This means that a parallel-installable library would end up packaged
  like libsdl3-dev, but a non-parallel-installable library ends up
  packaged like libfontconfig-dev, and both are correct. libsdl-dev would
  be wrong, and so would libfontconfig2-dev.

  - Another way to view this would be to say that the -dev package
    should always be {libraryname}-dev, but the developer-facing name
    of a parallel-installable library is actually a string that includes
    the version number: it's "SDL3" or "gtk-4", not "SDL" or "GTK".

* For existing libraries, prefer to keep the existing package naming:
  backwards compatibility is valuable and breaking it is disruptive.
  If the -dev package is going to be renamed for some other reason, then
  its new name should be as above.

* If the library's developer-facing name is inconsistently versioned or
  not (like libtiff, which is variously libtiff or libtiff-4) then the
  maintainer will need to choose one of its names, probably the one that
  they expect to be used most frequently, and use that one to choose how
  they name the -dev package.

The name of Policy §8 is "Shared libraries", but all of this applies
equally to static-only libraries: a static library like libfoo.a should
usually be in libfoo-dev, and a static library like libfoo-1.a should be
in libfoo-1-dev.

Does this make sense to the Policy team? Should I try to write some
Policy wording to capture this design?

Thanks,
    smcv

[1] https://ometer.com/parallel.html,
    archived for posterity:
https://web.archive.org/web/20260723160245/ometer.com/parallel.html