Recommend the use of ManifestStaticFilesStorage. Fixes #3700

docs/advanced_topics/deploying.rst

@@ -28,8 +28,19 @@ On other PAASs and IAASs
 
 We know of Wagtail sites running on `Heroku <http://spapas.github.io/2014/02/13/wagtail-tutorial/>`_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute </contributing/index>` your notes to this documentation!
 
+Deployment tips
+~~~~~~~~~~~~~~~
+
+Static files
+++++++++++++
+
+As with all Django projects, static files are not served by the Django application server in production (i.e. outside of the ``manage.py runserver`` command); these need to be handled separately at the web server level. See `Django's documentation on deploying static files <https://docs.djangoproject.com/en/stable/howto/static-files/deployment/>`_.
+
+The JavaScript and CSS files used by the Wagtail admin frequently change between releases of Wagtail - it's important to avoid serving outdated versions of these files due to browser or server-side caching, as this can cause hard-to-diagnose issues. We recommend enabling `ManifestStaticFilesStorage <https://docs.djangoproject.com/en/stable/ref/contrib/staticfiles/#manifeststaticfilesstorage>`_ in the ``STATICFILES_STORAGE`` setting - this ensures that different versions of files are assigned distinct URLs.
+
+
 Cloud storage
-~~~~~~~~~~~~~
++++++++++++++
 
 Wagtail follows `Django's conventions for managing uploaded files <https://docs.djangoproject.com/en/stable/topics/files/>`_, and can be configured to store uploaded images and documents on a cloud storage service such as Amazon S3; this is done through the `DEFAULT_FILE_STORAGE <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DEFAULT_FILE_STORAGE>`_ setting in conjunction with an add-on package such as `django-storages <https://django-storages.readthedocs.io/>`_. Be aware that setting up remote storage will not entirely offload file handling tasks from the application server - some Wagtail functionality requires files to be read back by the application server. In particular, documents are served through a Django view in order to enforce permission checks, and original image files need to be read back whenever a new resized rendition is created.
 

docs/releases/upgrading.rst

@@ -72,6 +72,8 @@ To upgrade:
 * Make any necessary code changes as directed in the "Upgrade considerations" section of the release notes.
 * Test that your project is working as expected.
 
+Remember that the JavaScript and CSS files used in the Wagtail admin may have changed between releases - if you encounter erratic behaviour on upgrading, ensure that you have cleared your browser cache. When deploying the upgrade to a production server, be sure to run ``./manage.py collectstatic`` to make the updated static files available to the web server. In production, we recommend enabling `ManifestStaticFilesStorage <https://docs.djangoproject.com/en/stable/ref/contrib/staticfiles/#manifeststaticfilesstorage>`_ in the ``STATICFILES_STORAGE`` setting - this ensures that different versions of files are assigned distinct URLs.
+
 
 .. _compatible_django_python_versions:
 

wagtail/project_template/project_name/settings/base.py

@@ -142,6 +142,11 @@ STATICFILES_DIRS = [
     os.path.join(PROJECT_DIR, 'static'),
 ]
 
+# ManifestStaticFilesStorage is recommended in production, to prevent outdated
+# Javascript / CSS assets being served from cache (e.g. after a Wagtail upgrade).
+# See https://docs.djangoproject.com/en/{{ docs_version }}/ref/contrib/staticfiles/#manifeststaticfilesstorage
+STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
+
 STATIC_ROOT = os.path.join(BASE_DIR, 'static')
 STATIC_URL = '/static/'