Improve documentation on float to top usage

1 files changed, 13 insertions, 0 deletions

diff --git a/docs/upgrade_guides/5.0.0.md b/docs/upgrade_guides/5.0.0.md
index d20efa1d..d5d518e8 100644
--- a/docs/upgrade_guides/5.0.0.md
+++ b/docs/upgrade_guides/5.0.0.md
@@ -11,6 +11,16 @@ Related documentation:
 !!! important - "If you use pre-commit remove seed-isort-config."
     If you currently use pre-commit, make sure to see the pre-commit section of this document. In particular, make sure to remove any `seed-isort-config` pre-step.
 
+## Imports no Longer Moved to Top
+
+One of the most immediately evident changes when upgrading to isort 5, is it now avoids moving imports around code by default.
+The great thing about this is that it means that isort can safely run against complex code bases that need to place side effects between import sections without needing any comments, flags, or configs. It's also part of the rearchitecting that allows it to sort within type checking conditionals and functions. However, it can be a jarring change
+for those of us who have gotten used to placing imports right above their usage in code to avoid context switching. No need to worry! isort still supports this work mode.
+
+If you want to move all imports to the top, you can use the new`--float-to-top` flag in the CLI or `float_to_top=true` option in your config file.
+
+See: [https://timothycrosley.github.io/isort/docs/configuration/options/#float-to-top](https://timothycrosley.github.io/isort/docs/configuration/options/#float-to-top)
+
 ## Migrating CLI options
 
 ### `--dont-skip` or `-ns`
@@ -29,6 +39,9 @@ The option was originally added to allow working around this, and was then turne
 ### `-ac`, `-wl`, `-ws`, `-tc`, `-sp`, `-sp`, `-sl`, `-sg`, `-sd`, `-rr`, `-ot`, `-nlb`, `-nis`, `-ls`, `-le`, `-lbt`, `-lai`, `-fss`, `-fgw`, `-ff`, `-fass`, `-fas`, `-dt`, `-ds`, `-df`, `-cs`, `-ca`, `-af`, `-ac`
 Two-letter shortened setting names (like `ac` for `atomic`) now require two dashes to avoid ambiguity. Simply add another dash before the option, or switch to the long form option to fix (example: `--ac` or `--atomic`).
 
+### `-v` and `-V`
+The `-v` (previously for version now for verbose) and `-V` (previously for verbose and now for version) options have been swapped to be more consistent with tools across the CLI and in particular Python ecosystem.
+
 ## Migrating Config options
 
 The first thing to keep in mind is how isort loads config options has changed in isort 5. It will no longer merge multiple config files, instead you must have 1 isort config per a project.