diff --git a/docs/releases/3.1.rst b/docs/releases/3.1.rst
index 4f346516cf..33f9ba154f 100644
--- a/docs/releases/3.1.rst
+++ b/docs/releases/3.1.rst
@@ -7,6 +7,56 @@ Released: XX, 2018
 What's new
 ==========
 
+- Improve database vendor migration support.
+- Add convertdb management command.
+- Fix crop transformation argument parsing. Thanks to Jordan Wages
+  (@wagesj45). Closes GitLab issue #490
+- Add error checking to the crop transformation arguments.
+- Fix post login redirection to honor the ?next= URL query string
+  argument. Thanks go to K.C. Wong (@dvusboy1). Closes GitLab
+  issue #489.
+- Update dropzone.js' timeout from 30 seconds to 120 to allow upload
+  of large files on slow connections.
+- Increase gunicorn's timeout from 30 seconds to 120.
+- Update packages versions: Pillow:5.2.0, PyYAML:3.13, django-environ:0.4.5,
+  django-model-utils:3.1.2, django-mptt:0.9.1, django-widget-tweaks: 1.4.2,
+  flanker:0.9.0, flex:6.13.2, furl:1.2, gevent:1.3.5, graphviz: 0.8.4,
+  gunicorn:19.9.0, pyocr:0.5.2, python-dateutil:2.7.3
+- Remove use of django-compressor and cssmin now that the project used
+  Whitenoise.
+- Display error when attempting to recalculate the page count of an empty
+  document (document stub that has no document version).
+- Add support for client side caching of document page images. The time
+  the images are cached is controlled by the new setting
+  DOCUMENTS_PAGE_IMAGE_CACHE_TIME which defaults to 31556926 seconds (1 year).
+- The document quick label selection field now uses a select2 widget.
+- Include querystring when force reload of a bare template view.
+- Speed up document image fade in reveal.
+- Use reseteable timer to ensure more document panels heights are matched.
+- Rewrote Mayan's Javascript suite MayanApp into ECMAScript2015.
+- Remove use is waitForJQuery.
+- Remove code statistics from the documentation.
+- Remove the pending work chapter. This is now available in the Wiki:
+  wiki.mayan-edms.com
+- Unify template title rendering.
+- Add support for template subtitles.
+- Make sure the on entry action of the initial state of workflows
+  executes on document creation.
+- Add new document app events: document type created and document type
+  edited.
+- Add link to document type events.
+- Add new metadata app events: metadata type created, metadata type edited,
+  metadata type to document type relationship update.
+- Add link to metadata type events.
+- Add support for subscribing to metadata type events.
+- Add link to view the events of a tag.
+- Add support for subscribing to the events of a tag.
+- Add the tag events view permissions to the tag model ACL.
+- Hide the title link of documents in the trash.
+- Add support for document metadata events: add, edit and remove.
+- Add workflow action to update the label and description of a document.
+
+
 Removals
 --------
 - None
@@ -15,12 +65,16 @@ Upgrading from a previous version
 ---------------------------------
 
 
-Using PIP
-~~~~~~~~~
+If installed via Python's PIP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Remove deprecated requirements::
+
+    $ curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt | pip uninstall -r /dev/stdin
 
 Type in the console::
 
-    $ pip install mayan-edms==3.0.1
+    $ pip install mayan-edms==3.1
 
 the requirements will also be updated automatically.
 
@@ -36,6 +90,10 @@ If you installed Mayan EDMS by cloning the Git repository issue the commands::
 otherwise download the compressed archived and uncompress it overriding the
 existing installation.
 
+Remove deprecated requirements::
+
+    $ pip uninstall -y -r removals.txt
+
 Next upgrade/add the new requirements::
 
     $ pip install --upgrade -r requirements.txt
@@ -43,6 +101,7 @@ Next upgrade/add the new requirements::
 
 Common steps
 ~~~~~~~~~~~~
+Perform these steps after updating the code from either step above.
 
 Migrate existing database schema with::
 
@@ -63,6 +122,6 @@ Backward incompatible changes
 Bugs fixed or issues closed
 ===========================
 
-* `GitLab issue #486 <https://gitlab.com/mayan-edms/mayan-edms/issues/486>`_ Docker Verison 3.0 not working
+* `GitLab issue #259 <https://gitlab.com/mayan-edms/mayan-edms/issues/259>`_ Thumbnails: why are they created on the fly (therefore: not cached)
 
 .. _PyPI: https://pypi.python.org/pypi/mayan-edms/