diff options
| -rw-r--r-- | doc/abi.rst | 16 | ||||
| -rw-r--r-- | doc/manual/abi.rst | 21 | ||||
| -rw-r--r-- | doc/manual/contents.rst | 3 | ||||
| -rw-r--r-- | doc/manual/deprecated.rst (renamed from doc/deprecated.txt) | 7 |
4 files changed, 28 insertions, 19 deletions
diff --git a/doc/abi.rst b/doc/abi.rst deleted file mode 100644 index 0fa26d21b..000000000 --- a/doc/abi.rst +++ /dev/null @@ -1,16 +0,0 @@ - -API/ABI Stability -==================== - -API of release branches is stable; that is to say code that compiles and works -against 2.0.0 should also compile with all later 2.x.x versions. The API on -master is completely fair game and may change at any time. - -Maintaining a consistent ABI while evolving a complex C++ API is exceedingly -expensive in development time. It is likely ABI breakage will occur at least -occasionally even in release branches. In these cases, the soname revision will -increase to prevent applications from linking against a potentially incompatible -version at runtime. - -You can review a report on ABI changes to Botan at -https://abi-laboratory.pro/tracker/timeline/botan/ diff --git a/doc/manual/abi.rst b/doc/manual/abi.rst new file mode 100644 index 000000000..888f0c33a --- /dev/null +++ b/doc/manual/abi.rst @@ -0,0 +1,21 @@ + +ABI Stability +==================== + +Botan uses semantic versioning for the API; if API features are added the minor +version increases, whereas if API compatability breaks occur the major version +is increased. + +However no guarantees about ABI are made between releases. Maintaining an ABI +compatible release in a complex C++ API is exceedingly expensive in development +time; just adding a single member variable or virtual function is enough to +cause ABI issues. + +If ABI changes, the soname revision will increase to prevent applications from +linking against a potentially incompatible version at runtime. + +If you are concerned about long-term ABI issues, considering using the C API +instead; this subset *is* ABI stable. + +You can review a report on ABI changes to Botan at +https://abi-laboratory.pro/tracker/timeline/botan/ diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst index 941bf014e..e33876b9e 100644 --- a/doc/manual/contents.rst +++ b/doc/manual/contents.rst @@ -42,4 +42,5 @@ Contents side_channels packaging fuzzing - + deprecated + abi diff --git a/doc/deprecated.txt b/doc/manual/deprecated.rst index cbb48c797..8cfe7e590 100644 --- a/doc/deprecated.txt +++ b/doc/manual/deprecated.rst @@ -1,3 +1,6 @@ +Deprecated Features +======================== + The following functionality is currently deprecated, and will likely be removed in a future release. If you think you have a good reason to be using one of the following, contact the developers to explain your @@ -6,9 +9,9 @@ use case if you want to make sure your code continues to work. This is in addition to specific API calls marked with BOTAN_DEPRECATED in the source. -- The headers botan.h, init.h, lookup.h +- The headers ``botan.h``, ``init.h``, ``lookup.h`` -- All or nothing package transform +- All or nothing package transform (``package.h``) - The TLS constructors taking `std::function` for callbacks. Instead use the TLS::Callbacks interface. |