From 6fac5df53598e6dedb806121ae40261d7491a341 Mon Sep 17 00:00:00 2001
From: Jeff Forcier <jeff@bitprophet.org>
Date: Fri, 21 Mar 2014 17:28:19 -0700
Subject: [PATCH] Start an FAQ and answer it with a new install section

---
 sites/www/faq.rst        |  9 +++++++++
 sites/www/index.rst      |  1 +
 sites/www/installing.rst | 24 ++++++++++++++++++++++++
 3 files changed, 34 insertions(+)
 create mode 100644 sites/www/faq.rst

diff --git a/sites/www/faq.rst b/sites/www/faq.rst
new file mode 100644
index 0000000..a7e8001
--- /dev/null
+++ b/sites/www/faq.rst
@@ -0,0 +1,9 @@
+===================================
+Frequently Asked/Answered Questions
+===================================
+
+Which version should I use? I see multiple active releases.
+===========================================================
+
+Please see :ref:`the installation docs <release-lines>` which have an explicit
+section about this topic.
diff --git a/sites/www/index.rst b/sites/www/index.rst
index a8e7262..0864dec 100644
--- a/sites/www/index.rst
+++ b/sites/www/index.rst
@@ -13,6 +13,7 @@ usage and API documentation can be found at our code documentation site,
 
 .. toctree::
     changelog
+    faq
     installing
     contributing
     contact
diff --git a/sites/www/installing.rst b/sites/www/installing.rst
index 955a0a5..7d61632 100644
--- a/sites/www/installing.rst
+++ b/sites/www/installing.rst
@@ -2,6 +2,8 @@
 Installing
 ==========
 
+.. _paramiko-itself:
+
 Paramiko itself
 ===============
 
@@ -23,6 +25,28 @@ PyCrypto C extension. `ecdsa` is easily installable from wherever you
 obtained Paramiko's package; PyCrypto may require more work. Read on for
 details.
 
+.. _release-lines:
+
+Release lines
+-------------
+
+Users desiring stability may wish to pin themselves to a specific release line
+once they first start using Paramiko; to assist in this, we guarantee bugfixes
+for at least the last 2-3 releases including the latest stable one. This currently means Paramiko **1.11** through **1.13**.
+
+If you're unsure which version to install, we have suggestions:
+
+* **Completely new users** should always default to the **latest stable
+  release** (as above, whatever is newest / whatever shows up with ``pip
+  install paramiko``.)
+* **Users upgrading from a much older version** (e.g. the 1.7.x line) should
+  probably get the **oldest actively supported line** (see the paragraph above
+  this list for what that currently is.)
+* **Everybody else** is hopefully already "on" a given version and can
+  carefully upgrade to whichever version they care to, when their release line
+  stops being supported.
+
+
 PyCrypto
 ========