DEPRECATE: new doc describing planned item removals

Closes #2704

2 files changed, 78 insertions, 0 deletions

diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md
new file mode 100644
index 000000000..681593b61
--- /dev/null
+++ b/docs/DEPRECATE.md
@@ -0,0 +1,77 @@
+# Items to be removed from future curl releases
+
+If any of these deprecations is a cause for concern for you, please email the
+curl-library mailing list as soon as possible and explain to us why this is a
+problem for you and how your use case can't be satisfied properly using a work
+around.
+
+## axTLS backend
+
+Here are some complaints on axTLS.
+
+ - home page without HTTPS
+ - doesn't support modern TLS features like SNI? [1]
+ - lacks support for modern ciphers [5]
+ - doesn't allow for outside bug report submissions [2]
+ - there's virtually no discussion about it on [3] and [4]
+
+Combined, this list hints that this is not a library and project we should
+recommend to users.
+
+[1] = https://github.com/dsheets/axtls/issues/2
+[2] = https://sourceforge.net/p/axtls/bugs/
+[3] = https://sourceforge.net/p/axtls/discussion/
+[4] = https://sourceforge.net/p/axtls/mailman/axtls-general/
+[5] = https://github.com/micropython/micropython/issues/3198
+
+### State
+
+Since June 1st (curl 7.61.0) axTLS support is disabled in code and
+requires a small code change to build without errors.
+
+### Removal
+
+Remove all axTLS related code from curl on December 1st, exactly six months
+after previouslt mentioned commit. To be shiped on December 26 (possibly
+called version 7.64.0)
+
+## HTTP Pipelining
+
+HTTP Pipelining is badly supported by curl in the sense that we have bugs and
+it is a fragile feature without enough tests. Also, when something turns out
+to have problems it is really tricky to debug due to the timing sensitivy so
+very often enabling debug outputs or similar completely changes the nature of
+the behavior and things are not reproducing anymore!
+
+HTTP Pipelining was never enabled by default by the large desktop browsers due
+to all the issues with it. Both Firefox and Chrome have also dropped
+Pipelining support entirely since a long time back now. We are in fact over
+time becoming more and more lonely in supporting pipelining.
+
+The bad state of HTTP pipelining was a primary driving factor behind HTTP/2
+and its multiplexing feature. HTTP/2 multiplexing is truly and really
+"pipelining done right". It is way more solid, practical and solves the use
+case in a better way with better performance and fewer downsides and problems.
+
+In 2018, pipelining *should* be abandoned and HTTP/2 should be used instead.
+
+### State
+
+In 7.62.0 (release planned to happen in September 2018), we add code
+that ignores the "enable pipeline" option setting). The *setopt() function
+would still return "OK" though so the application couldn't tell that this is
+happening.
+
+Users who truly need pipelining from that version will need to modify the code
+(ever so slightly) and rebuild.
+
+### Removal
+
+Six months later, in sync with the planned release happen in April 2019,
+(might be 7.66.0), assuming no major riots have occurred due to this in the
+mean time, we rip out the pipelining code. It is in the order of 1000 lines of
+libcurl code.
+
+Left to answer: should the *setopt() function start to return error when these
+options are set to be able to tell when they're trying to use options that are
+no longer around or should we maintain behavior as much as possible?
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 68ab5d45f..3c0296784 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -50,6 +50,7 @@ EXTRA_DIST =                                    \
  CODE_OF_CONDUCT.md                             \
  CODE_STYLE.md                                  \
  CONTRIBUTE.md                                  \
+ DEPRECATE.md                                   \
  FAQ                                            \
  FEATURES                                       \
  GOVERNANCE.md                                  \