From 560e0f7334e89536e9767bd4b3e606e2c03e97ae Mon Sep 17 00:00:00 2001
From: jack1142 <6032823+jack1142@users.noreply.github.com>
Date: Sun, 26 Apr 2020 19:35:59 +0200
Subject: [PATCH] Add docs for updating Red (#3790)

* wip

* Add 3.0.2 or older instructions

* rephrase

* emphasis

* another rephrase

* Add 3.2.0+ instructions for Linux & Mac

* change indents
---
 docs/index.rst      |   1 +
 docs/update_red.rst | 124 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 125 insertions(+)
 create mode 100644 docs/update_red.rst

diff --git a/docs/index.rst b/docs/index.rst
index 95dce9158..64408672c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Welcome to Red - Discord Bot's documentation!
 
     install_windows
     install_linux_mac
+    update_red
     about_venv
     autostart_systemd
     autostart_pm2
diff --git a/docs/update_red.rst b/docs/update_red.rst
new file mode 100644
index 000000000..dd3ef768c
--- /dev/null
+++ b/docs/update_red.rst
@@ -0,0 +1,124 @@
+============
+Updating Red
+============
+
+Updating to the latest version of Red has several benefits:
+
+- New features and improvements are added.
+- Bugs are fixed.
+- Your bot is safe from security vulnerabilities that have been found.
+
+Here are some things to consider to help make your upgrade as smooth as possible.
+
+.. note::
+
+    If you're developing for Red, you should also look for "Breaking changes" sections in release notes for each minor (X.Y.0) version that's been released since you last updated Red.
+
+Updating differs depending on the version you currently have. Next sections will explain how to upgrade to latest version of Red (|version|) from the version that is in the header of the section.
+
+
+Red 3.2.0 or newer
+******************
+
+Windows
+-------
+
+If you have Red 3.2.0 or newer, all you have to do to upgrade Red is running 2 commands.
+
+1. Activate your venv with the following command:
+
+    .. code:: none
+
+        "%userprofile%\redenv\Scripts\activate.bat"
+
+2. Update Red with this command:
+
+    .. code:: none
+
+        python -m pip install -U Red-DiscordBot
+
+.. attention::
+
+    If you're using PostgreSQL data backend, replace ``Red-DiscordBot`` in the second command with ``Red-DiscordBot[postgres]``
+
+Linux & Mac
+-----------
+
+If you have Red 3.2.0 or newer, all you have to do to upgrade Red is running 2 commands.
+
+1. Activate your virtual environment.
+  
+    If you used ``venv`` for your virtual environment, use:
+
+    .. code:: none
+
+        source ~/redenv/bin/activate
+
+    If you used ``pyenv`` for your virtual environment, use:
+
+    .. code:: none
+
+        pyenv shell <name>
+
+2. Update Red with this command:
+
+    .. code:: none
+
+        python -m pip install -U Red-DiscordBot
+
+.. attention::
+
+    If you're using PostgreSQL data backend, replace ``Red-DiscordBot`` in the second command with ``Red-DiscordBot[postgres]``
+
+
+Red 3.1.X
+*********
+
+If you have Red 3.1.X, you will need to follow the install instructions for your operating system:
+
+- `Windows <install_windows>`
+- `Linux & Mac <install_linux_mac>`
+
+Follow every step to ensure you have all dependencies up-to-date and only skip ``redbot-setup`` step as you already have a bot instance.
+
+If you already have Red installed in a virtual environment, you will need to delete it before starting this process.
+
+.. attention::
+
+    Red 3.2 dropped support for the MongoDB driver
+
+     - If you were not using the MongoDB driver, this does not affect you.
+     - If you were using a 3rd party cog which required MongoDB, it probably still does.
+     - If you were using the MongoDB driver, **prior to launching your instance after update**,
+       you will need to run the following commands to convert:
+
+         .. code::
+
+           python -m pip install dnspython~=1.16.0 motor~=2.0.0 pymongo~=3.8.0
+           redbot-setup convert [instancename] json
+
+
+Red 3.0.2 and older
+*******************
+
+.. important::
+
+    Red 3.2 dropped support for the MongoDB driver
+
+     - If you were not using the MongoDB driver, this does not affect you.
+     - If you were using a 3rd party cog which required MongoDB, it probably still does.
+     - If you were using the MongoDB driver, **prior to updating**, you will need to convert your data to JSON backend,
+       using following command:
+
+         .. code::
+
+           redbot-setup --edit
+
+If you have Red 3.0.2 or older, you will need to follow the install instructions for your operating system:
+
+- `Windows <install_windows>`
+- `Linux & Mac <install_linux_mac>`
+
+Follow every step to ensure you have all dependencies up-to-date and only skip ``redbot-setup`` step as you already have a bot instance.
+
+If you already have Red installed in a virtual environment, you will need to delete it before starting this process.