The kernel header installed alongside its dynamic library should be versioned. Versioning best practices around providing a stable API are well established, e.g. through semantic versioning. However the library presents challenges to versioning beyond API stability. Internal features changing, i.e. a new soft fork rule, or a new validation cache, might not have a direct impact on the API, but won’t necessarily be desirable to run by all users. It also currently uses clientversion.cpp, which dictates the underlying Bitcoin Core version. Since Bitcoin Core’s version in turn does not communicate anything about the state of the API, it should not be directly re-used for the header’s versioning.
A solution to this might be to have a version for the API and treat the Bitcoin Core version as a product name. This could divorce the release of the header and the library from the rest of Bitcoin Core. A full version string could look something like v1.0.0 (Core-v31.0). This could also mean that the same API version supports different “product names” and vice-versa.
Another alternative to consider here is to provide a unified version for the header and bump its patch number on every change to the library.