diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md
index b36bb9f88..b5d70a48d 100644
--- a/docs/en/03_Upgrading/index.md
+++ b/docs/en/03_Upgrading/index.md
@@ -598,17 +598,36 @@ Execute the upgrade command with this command.
 upgrade-code upgrade ./mysite/ --write
 ```
 
-If you omit the `--write` flag you will get a preview of what change the upgrader will apply to your codebase. This can be helpful if you if you are tweaking your `.upgrade.yml` or if you are trying to identify areas where you should add a `@skipUpgrade` statement,
+If you omit the `--write` flag you will get a preview of what change the upgrader will apply to your codebase. This can be helpful if you are tweaking your `.upgrade.yml` or if you are trying to identify areas where you should add a `@skipUpgrade` statement,
 
 You can also tweak which rules to apply with the `--rule` flag: `code`, `config`, and `lang`. For example, the following command will only upgrade `lang` and `config` files:
 ```bash
 upgrade-code upgrade ./mysite/ --rule=config --rule=lang
 ```
 
-The `upgrade` command can alter big chunks of your codebase. While it works reasonably well in most use case, you should not trust it blindly. You should take time to review all changes applied by the `upgrade` command and confirm you are happy with them.
+The `upgrade` command can alter big chunks of your codebase. While it works reasonably well in most use cases, you should not trust it blindly. You should take time to review all changes applied by the `upgrade` command and confirm you are happy with them.
 
 [Continue to "Finalising namespace updates"](#namespace-finalise)
 
+#### Rename Warnings
+
+You can also show extra warnings for potentially ambiguous mappings with the `renameWarnings` property:
+
+```yaml
+renameWarnings:
+  - File
+  - Image
+```
+
+An example of an ambiguous rename would be:
+```PHP
+private static $has_one = [
+    'Image' => 'Image',
+];
+```
+
+Add the `--prompt` flag to manually approve ambiguous class renames.
+
 ### Manually update namespaced references
 
 If you decide to update your namespace references by hand, you'll need to go through the entire code base and update them all from the old non-namespaced SilverStripe classes to the new namespaced equivalent. If you are referencing classes from third party modules that have been namespaced, you'll need to update those as well.