From c0a5a5863acc13a2d863d5bb9cabfaee0b30442d Mon Sep 17 00:00:00 2001
From: Jack Lloyd <jack@randombit.net>
Date: Mon, 4 Dec 2017 04:27:52 -0500
Subject: Move deprecated and ABI notices to the handbook

Probably easier to find for most users since the handbook is packaged
but the other stuff in doc isn't.
---
 doc/manual/abi.rst        | 21 +++++++++++++++++
 doc/manual/contents.rst   |  3 ++-
 doc/manual/deprecated.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 doc/manual/abi.rst
 create mode 100644 doc/manual/deprecated.rst

(limited to 'doc/manual')

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/manual/deprecated.rst b/doc/manual/deprecated.rst
new file mode 100644
index 000000000..8cfe7e590
--- /dev/null
+++ b/doc/manual/deprecated.rst
@@ -0,0 +1,57 @@
+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
+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``
+
+- All or nothing package transform (``package.h``)
+
+- The TLS constructors taking `std::function` for callbacks. Instead
+  use the TLS::Callbacks interface.
+
+- The Buffered_Computation base class. In a future release the class will be
+  removed, and all of member functions instead declared directly on
+  MessageAuthenticationCode and HashFunction. So this only affects you if you
+  are directly referencing `Botan::Buffered_Computation` in some way.
+
+- The SymmetricAlgorithm base class. Similarly to Buffered_Computation, in a
+  future release the class will be removed and its member functions copied to
+  classes which currently subclass it. This only affects your code if you
+  are referencing `Botan::SymmetricAlgorithm` directly.
+
+- Platform support for BeOS and IRIX operating systems
+
+- Support for PathScale and HP compilers
+
+- TLS: 3DES and SEED ciphersuites
+
+- TLS: Anonymous DH/ECDH ciphersuites
+
+- TLS: DSA ciphersuites/certs
+
+- TLS: static RSA key exchange ciphersuites
+
+- TLS: CCM_8 ciphersuites
+
+- Block ciphers CAST-256, Kasumi, MISTY1, and DESX.
+
+- CBC-MAC, X9.19-MAC
+
+- PBKDF1 key derivation
+
+- GCM support for 64-bit tags
+
+- Old (Google specific) ChaCha20 TLS ciphersuites
+
+- All built in ECC groups < 256 bits
+
+- All built in MODP groups < 2048 bits
+
+- All pre-created DSA groups
-- 
cgit v1.2.3