Merge branch 'master' into docs-update-standalone-manual-plugins

4 files changed, 52 insertions, 57 deletions

diff --git a/docs/ciphers.rst b/docs/ciphers.rst
index 31ce45963..1b320cdf9 100644
--- a/docs/ciphers.rst
+++ b/docs/ciphers.rst
@@ -255,7 +255,7 @@ I have access to an English-language summary of the recommendations.
 Keylength.com
 ~~~~~~~~~~~~~
 
-Damien Giry collects recommendations by academic researchers and standards organizations about keylengths for particular cryptoperiods, years, or security levels.  The keylength recommendations of the various sources are summarized in a chart.  This site has been updated over time and includes expert guidance from eight sources published between 2000 and 2015.
+Damien Giry collects recommendations by academic researchers and standards organizations about keylengths for particular cryptoperiods, years, or security levels.  The keylength recommendations of the various sources are summarized in a chart.  This site has been updated over time and includes expert guidance from eight sources published between 2000 and 2017.
 
 http://www.keylength.com/
 
diff --git a/docs/cli-help.txt b/docs/cli-help.txt
index 4cb408002..9ef9d9e6c 100644
--- a/docs/cli-help.txt
+++ b/docs/cli-help.txt
@@ -86,7 +86,7 @@ optional arguments:
                         statistics about success rates by OS and plugin. If
                         you wish to hide your server OS version from the Let's
                         Encrypt server, set this to "". (default:
-                        CertbotACMEClient/0.11.1 (Ubuntu 16.04.1 LTS)
+                        CertbotACMEClient/0.12.0 (Ubuntu 16.04.2 LTS)
                         Authenticator/XXX Installer/YYY)
 
 automation:
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 5f939e947..5cdf86147 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -14,15 +14,24 @@ Getting Started
 Running a local copy of the client
 ----------------------------------
 
-Running the client in developer mode from your local tree is a little
-different than running ``certbot-auto``.  To get set up, do these things
-once:
+Running the client in developer mode from your local tree is a little different
+than running Certbot as a user. To get set up, clone our git repository by
+running:
 
 .. code-block:: shell
 
    git clone https://github.com/certbot/certbot
+
+If you're on macOS, we recommend you skip the rest of this section and instead
+run Certbot in Docker. You can find instructions for how to do this :ref:`here
+<docker>`. If you're running on Linux, you can run the following commands to
+install dependencies and set up a virtual environment where you can run
+Certbot. You only need to do this once.
+
+.. code-block:: shell
+
    cd certbot
-   ./letsencrypt-auto-source/letsencrypt-auto --os-packages-only
+   ./certbot-auto --os-packages-only
    ./tools/venv.sh
 
 Then in each shell where you're working on the client, do:
@@ -69,10 +78,8 @@ either in the same directory as ``foo.py`` or in the ``tests`` subdirectory
 (if there isn't, make one). While you are working on your code and tests, run
 ``python foo_test.py`` to run the relevant tests.
 
-For debugging, we recommend running ``pip install ipdb`` and putting
-``import ipdb; ipdb.set_trace()`` statements inside the source
-code. Alternatively, you can use Python's standard library `pdb`,
-but you won't get TAB completion.
+For debugging, we recommend putting
+``import ipdb; ipdb.set_trace()`` statements inside the source code.
 
 Once you are done with your code changes, and the tests in ``foo_test.py`` pass,
 run all of the unittests for Certbot with ``tox -e py27`` (this uses Python
@@ -285,8 +292,7 @@ Steps:
    including coverage. The ``--skip-missing-interpreters`` argument ignores
    missing versions of Python needed for running the tests. Fix any errors.
 5. If your code touches communication with an ACME server/Boulder, you
-   should run the integration tests, see `integration`_. See `Known Issues`_
-   for some common failures that have nothing to do with your code.
+   should run the integration tests, see `integration`_.
 6. Submit the PR.
 7. Did your tests pass on Travis? If they didn't, fix any errors.
 
@@ -346,56 +352,36 @@ This should generate documentation in the ``docs/_build/html``
 directory.
 
 
-Other methods for running the client
-====================================
+.. _docker:
 
-Vagrant
--------
-
-If you are a Vagrant user, Certbot comes with a Vagrantfile that
-automates setting up a development environment in an Ubuntu 14.04
-LTS VM. To set it up, simply run ``vagrant up``. The repository is
-synced to ``/vagrant``, so you can get started with:
-
-.. code-block:: shell
+Running the client with Docker
+==============================
 
-  vagrant ssh
-  cd /vagrant
-  sudo ./venv/bin/certbot
+You can use Docker Compose to quickly set up an environment for running and
+testing Certbot. This is especially useful for macOS users. To install Docker
+Compose, follow the instructions at https://docs.docker.com/compose/install/.
 
-Support for other Linux distributions coming soon.
+.. note:: Linux users can simply run ``pip install docker-compose`` to get
+  Docker Compose after installing Docker Engine and activating your shell as
+  described in the :ref:`Getting Started <getting_started>` section.
 
-.. note::
-   Unfortunately, Python distutils and, by extension, setup.py and
-   tox, use hard linking quite extensively. Hard linking is not
-   supported by the default sync filesystem in Vagrant. As a result,
-   all actions with these commands are *significantly slower* in
-   Vagrant. One potential fix is to `use NFS`_ (`related issue`_).
+Now you can develop on your host machine, but run Certbot and test your changes
+in Docker. When using ``docker-compose`` make sure you are inside your clone of
+the Certbot repository. As an example, you can run the following command to
+check for linting errors::
 
-.. _use NFS: http://docs.vagrantup.com/v2/synced-folders/nfs.html
-.. _related issue: https://github.com/ClusterHQ/flocker/issues/516
+  docker-compose run --rm --service-ports development bash -c 'tox -e lint'
 
+You can also leave a terminal open running a shell in the Docker container and
+modify Certbot code in another window. The Certbot repo on your host machine is
+mounted inside of the container so any changes you make immediately take
+effect. To do this, run::
 
-Docker
-------
-
-OSX users will probably find it easiest to set up a Docker container for
-development. Certbot comes with a Dockerfile (``Dockerfile-dev``)
-for doing so. To use Docker on OSX, install and setup docker-machine using the
-instructions at https://docs.docker.com/installation/mac/.
-
-To build the development Docker image::
-
-  docker build -t certbot -f Dockerfile-dev .
-
-Now run tests inside the Docker image:
-
-.. code-block:: shell
+  docker-compose run --rm --service-ports development bash
 
-  docker run -it certbot bash
-  cd src
-  tox -e py27
+Now running the check for linting errors described above is as easy as::
 
+  tox -e lint
 
 .. _prerequisites:
 
diff --git a/docs/using.rst b/docs/using.rst
index c162e2fde..7c17796e7 100644
--- a/docs/using.rst
+++ b/docs/using.rst
@@ -144,6 +144,10 @@ the ``--nginx`` flag on the commandline.
 Standalone
 ----------
 
+Use standalone mode to obtain a cert if you don't want to use (or don't currently have)
+existing server software. The standalone plugin does not rely on any other server
+software running on the machine where you obtain the cert.
+
 To obtain a cert using a "standalone" webserver, you can use the
 standalone plugin by including ``certonly`` and ``--standalone``
 on the command line. This plugin needs to bind to port 80 or 443 in
@@ -154,10 +158,8 @@ one of the options shown below on the command line.
     * ``--preferred-challenges http`` to use port 80
     * ``--preferred-challenges tls-sni`` to use port 443
 
-The standalone plugin does not rely on any other server software running
-on the machine where you obtain the certificate. It must still be possible
-for that machine to accept inbound connections from the Internet on the
-specified port using each requested domain name.
+It must still be possible for your machine to accept inbound connections from
+the Internet on the specified port using each requested domain name.
 
 .. note:: The ``--standalone-supported-challenges`` option has been
    deprecated since ``certbot`` version 0.9.0.
@@ -429,6 +431,13 @@ Certbot is working hard to improve the renewal process, and we
 apologize for any inconvenience you encounter in integrating these
 commands into your individual environment.
 
+.. note:: ``certbot renew`` exit status will only be 1 if a renewal attempt failed.
+  This means ``certbot renew`` exit status will be 0 if no cert needs to be updated.
+  If you write a custom script and expect to run a command only after a cert was actually renewed
+  you will need to use the ``--post-hook`` since the exit status will be 0 both on successful renewal
+  and when renewal is not necessary.
+
+
 Modifying the Renewal Configuration File
 ----------------------------------------