RFC: Add versioning to the kernel header #33911

1. 
   sedited commented at 8:19 pm on November 19, 2025: contributor

   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.

2. sedited added the label Feature on Nov 19, 2025
3. ?
   added_to_project_v2 sedited
4. ?
   project_v2_item_status_changed sedited
5. 
   fanquake commented at 10:46 am on November 26, 2025: member

   I think anything is probably fine here (at this point), as long as any versioning doesn’t become a burden on productivity. I think the API should remain experimental, and no guarantees about backwards compatibility or stability should be made. If the need arises, we should be free to completely rewrite or re-architect (in a breaking way) anything we have released. We currently have a small, reactive group implementing things on top of the API, who I think will be willing to continue to rewrite/adapt their code as we flesh out what this should look like, and their contributions/feedback are taken onboard.
6. 
   maflcko commented at 11:02 am on November 26, 2025: member

   It is probably fine for the first few releases to just treat the Bitcoin Core FormatFullVersion() as the kernel version. It is clear that that version does not follow the semantic versioning of the kernel API, but if kernel users care about breaking changes, they will be listed in the release notes anyway.

Contributors
sedited fanquake maflcko

Labels
Feature