docs: Tweak the release notes and deployment docs following testing.

4 files changed, 60 insertions, 53 deletions

diff --git a/docs/source/plugindocs/subtitles.rst b/docs/source/plugindocs/subtitles.rst
new file mode 100644
index 00000000..5b1be9f6
--- /dev/null
+++ b/docs/source/plugindocs/subtitles.rst
@@ -0,0 +1 @@
+.. include:: ../../../mediagoblin/plugins/subtitles/README.rst
diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst
index 2e3fc992..b7e7a737 100644
--- a/docs/source/siteadmin/deploying.rst
+++ b/docs/source/siteadmin/deploying.rst
@@ -65,18 +65,22 @@ MediaGoblin has the following core dependencies:
 - `virtualenv <http://www.virtualenv.org/>`_
 - `Node.js <https://nodejs.org>`_
 
-On a DEB-based system (e.g Debian, Trisquel, Ubuntu and
-derivatives) issue the following commands:
+These instructions have been tested on Debian 10, CentOS 8 and
+Fedora 31. These instructions should approximately translate to recent
+Debian derivatives such as Ubuntu 18.04 and Trisquel 8, and to relatives of
+Fedora such as CentOS 8.
+
+Issue the following commands:
 
 .. code-block:: bash
 
-    # Debian, Trisquel, Ubuntu and derivatives (Hereafter Debian and co.)
+    # Debian 10
     sudo apt update
     sudo apt install automake git nodejs npm python3-dev python3-gi \
     python3-gst-1.0 python3-lxml python3-pil virtualenv
 
-    # Fedora, CentOS, RHEL and derivatives (Hereafter Fedora and co.)
-    dnf install automake gcc git-core make nodejs npm python3-devel \
+    # Fedora 31
+    sudo dnf install automake gcc git-core make nodejs npm python3-devel \
     python3-lxml python3-pillow virtualenv
 
 .. note::
@@ -84,32 +88,32 @@ derivatives) issue the following commands:
    MediaGoblin now uses Python 3 by default. To use Python 2, you may
    instead substitute from "python3" to "python" for most package
    names in the Debian instructions and this should cover dependency
-   installation. Python 2 installation has not been tested on Fedora
-   and co.
+   installation. Python 2 installation has not been tested on Fedora.
 
 For a production deployment, you'll also need Nginx as frontend web
 server and RabbitMQ to store the media processing queue::
 
-    # Debian and co.
+    # Debian
     sudo apt install nginx-light rabbitmq-server
 
-    # Fedora and co.
+    # Fedora
     sudo dnf install nginx rabbitmq-server
 
-.. note::
+..
+   .. note::
 
-   You might have to enable additional repositories under Fedora and
-   co. because rabbitmq-server might be not included in official
-   repositories. That looks like this for CentOS::
+      You might have to enable additional repositories under Fedora
+      because rabbitmq-server might be not included in official
+      repositories. That looks like this for CentOS::
 
-     sudo dnf config-manager --set-enabled centos-rabbitmq-38
-     sudo dnf config-manager --set-enabled PowerTools
-     sudo dnf install rabbitmq-server
-     sudo systemctl enable rabbitmq-server.service
-     # TODO: Celery repeatedly disconnects from RabbitMQ on CentOS 8.
+        sudo dnf config-manager --set-enabled centos-rabbitmq-38
+        sudo dnf config-manager --set-enabled PowerTools
+        sudo dnf install rabbitmq-server
+        sudo systemctl enable rabbitmq-server.service
+        # TODO: Celery repeatedly disconnects from RabbitMQ on CentOS 8.
 
-   As an alternative, you can try installing redis-server and
-   configure it as celery broker.
+      As an alternative, you can try installing redis-server and
+      configure it as celery broker.
 
 Configure PostgreSQL
 ~~~~~~~~~~~~~~~~~~~~
@@ -123,17 +127,17 @@ Configure PostgreSQL
 
 These are the packages needed for PostgreSQL::
 
-    # Debian and co.
+    # Debian
     sudo apt install postgresql python3-psycopg2
 
-    # Fedora and co.
+    # Fedora
     sudo dnf install postgresql postgresql-server python3-psycopg2
 
-Fedora and co. also requires that you initialize and start the
+Fedora also requires that you initialize and start the
 PostgreSQL database with a few commands. The following commands are
 not needed on a Debian-based platform, however::
 
-    # Feora and co.
+    # Feora
     sudo /usr/bin/postgresql-setup initdb
     sudo systemctl enable postgresql
     sudo systemctl start postgresql
@@ -178,11 +182,11 @@ The following command will create a system account with a username of
 
 If you are using a Debian-based system, enter this command::
 
-    # Debian and co.
-    sudo useradd --system --create-home --home-dir /var/lib/mediagoblin \
+    # Debian
+    sudo useradd --system --create-home --home-dir /var/lib/qmediagoblin \
     --group www-data --comment 'GNU MediaGoblin system account' mediagoblin
 
-    # Fedora and co.
+    # Fedora
     sudo useradd --system --create-home --home-dir /var/lib/mediagoblin \
     --group nginx --comment 'GNU MediaGoblin system account' mediagoblin
 
@@ -222,11 +226,11 @@ to the unprivileged system account.
 To do this, enter the following commands, changing the defaults to suit your
 particular requirements::
 
-    # Debian and co.
+    # Debian
     sudo mkdir --parents /srv/mediagoblin.example.org
     sudo chown --no-dereference --recursive mediagoblin:www-data /srv/mediagoblin.example.org
 
-    # Fedora and co.
+    # Fedora
     sudo mkdir --parents /srv/mediagoblin.example.org
     sudo chown --no-dereference --recursive mediagoblin:nginx /srv/mediagoblin.example.org
 
@@ -252,14 +256,15 @@ MediaGoblin directory that you just created::
 
 Clone the MediaGoblin repository and set up the git submodules::
 
-    $ git clone --depth=1 https://git.savannah.gnu.org/git/mediagoblin.git --branch stable
+    $ git clone --depth=1 https://git.savannah.gnu.org/git/mediagoblin.git \
+      --branch stable --recursive
     $ cd mediagoblin
-    $ git submodule init && git submodule update
 
 Set up the environment::
 
-    $ ./bootstrap.sh && VIRTUALENV_FLAGS='--system-site-packages' \
-    ./configure && make
+    $ ./bootstrap.sh
+    $ VIRTUALENV_FLAGS='--system-site-packages' ./configure
+    $ make
 
 .. note::
 
@@ -269,8 +274,7 @@ Set up the environment::
 Create and set the proper permissions on the ``user_dev`` directory.
 This directory will be used to store uploaded media files::
 
-    $ mkdir --mode='u=rwx,g=rx,o=' user_dev
-    $ chmod g+s user_dev
+    $ mkdir --mode=2750 user_dev
 
 This concludes the initial configuration of the MediaGoblin 
 environment. In the future, when you update your
@@ -375,12 +379,12 @@ into a directory that will be included in your ``nginx`` configuration
 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with the
 following commands::
 
-    # Debian and co.
+    # Debian
     sudo ln --symbolic /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/mediagoblin.conf
     sudo rm --force /etc/nginx/sites-enabled/default
     sudo systemctl enable nginx
 
-    # Fedora and co.
+    # Fedora
     sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/mediagoblin.conf
     sudo systemctl enable nginx
 
@@ -487,10 +491,10 @@ Try logging in and uploading an image. If after uploading you see any
 need to update the permissions on the new directories MediaGoblin has
 created::
 
-    # Debian and co.
+    # Debian
     sudo chown --no-dereference --recursive mediagoblin:www-data /srv/mediagoblin.example.org
 
-    # Fedora and co.
+    # Fedora
     sudo chown --no-dereference --recursive mediagoblin:nginx /srv/mediagoblin.example.org
 
 .. note::
diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst
index f47f1522..fe702d16 100644
--- a/docs/source/siteadmin/relnotes.rst
+++ b/docs/source/siteadmin/relnotes.rst
@@ -45,9 +45,10 @@ carefully, or at least skim over it.
 This release includes video subtitles and multiple video qualities and a swathe
 of smaller improvements and bug-fixes listed below.
 
-Python 3 is now the default when you install MediaGoblin. Python 2 is
-still supported in this release with `./configure --without-python3`, but
-support will likely be removed in the next release.
+Python 3 is now the default when you install MediaGoblin and is strongly
+recommended. Python 2 installation is still supported in this release with
+`./configure --without-python3`, but support will likely be removed in the next
+release.
 
 FastCGI support has now been deprecated and removed from the documentation as
 our dependency `flup` does not support Python 3.
@@ -64,25 +65,25 @@ our dependency `flup` does not support Python 3.
 
 **Upgrade (upgrading to Python 3):**
 
-0. Update to the latest release.  In your ``mediagoblin`` directory, run:
+0. Refer to the "Dependences" and "Configure PostgreSQL" sections of
+   ":doc:`deploying`" to install the necessary Python 3 dependencies.
+1. Update to the latest release.  In your ``mediagoblin`` directory, run:
    ``git fetch && git checkout -q v0.10.0``
-1. Remove your existing installation:
+2. Remove your existing installation:
    ``rm -rf bin include lib lib64``
-2. Upgrade MediaGoblin:
+3. Upgrade MediaGoblin:
    ``./bootstrap.sh && ./configure && make``
-3. Update the database:
-   ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
-4. Restart MediaGoblin
+4. Update the database:
+   ``./bin/gmg dbupdate``
+5. Restart MediaGoblin
 
-**Upgrade (remaining on Python 2):**
+**Upgrade (remaining on Python 2 - not recommended):**
 
 0. Update to the latest release.  In your ``mediagoblin`` directory, run:
    ``git fetch && git checkout -q v0.10.0``
-1. Remove your existing installation:
-   ``rm -rf bin include lib lib64``
-2. Update the database:
+1. Update the database:
    ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
-3. Restart MediaGoblin
+2. Restart MediaGoblin
 
 For detailed instructions on installing MediaGoblin, see ":doc:`deploying`". If
 you have any problems, please drop in to the `#mediagoblin IRC chat
diff --git a/setup.py b/setup.py
index 6dd7ce51..62365123 100644
--- a/setup.py
+++ b/setup.py
@@ -149,6 +149,7 @@ install_requires = [
     'PasteDeploy',
     'PasteScript',
     'requests>=2.6.0',
+    'certifi>=2017.4.17', # Reported to be a requirement on Fedora 31 (TODO: test)
     'PyLD<2.0.0', # Python 2, but also breaks a Python 3 test if >= 2.0.0.
     'ExifRead>=2.0.0',
     'email-validator', # Seems that WTForms must have dropped this.