Add upgrade guide

docs/upgrade_guides/5.0.0.md

@@ -0,0 +1,38 @@
+# Upgrading to 5.0.0
+
+isort 5.0.0 is the first major release of isort in 5 years, and as such it does introduce some breaking changes.
+This guide is meant to help migrate projects from using isort 4.x.x unto the 5.0.0 release.
+
+Related documentation:
+
+* [isort 5.0.0 changelog](https://timothycrosley.github.io/isort/CHANGELOG/#500-penny-july-4-2020)
+* [isort 5 release document](https://timothycrosley.github.io/isort/docs/major_releases/introducing_isort_5/)
+
+## Migrating CLI options
+
+### `--dont-skip` or `-ns`
+In an earlier version isort had a default skip of `__init__.py`. To get around that many projects wanted a way to not skip `__init__.py` or any other files that were automatically skipped in the future by isort. isort no longer has any default skips, so if the value here is `__init__.py` you can simply remove the command line option. If it is something else, just make sure you aren't specifying to skip that file somewhere else in your config.
+
+### `--recursive` or `-rc`
+Prior to version 5.0.0, isort wouldn't automatically traverse directories. The --recursive option was necessary to tell it to do so. In 5.0.0 directories are automatically traversed for all Python files, and as such this option is no longer necessary and should simply be removed.
+
+### `--apply` or `-y`
+Prior to version 5.0.0, depending on how isort was executed, it would ask you before making every file change. In isort 5.0.0 file changes happen by default inline with other formatters. `--interactive` is available to restore the previous behavior. If encountered this option can simply be removed.
+
+### `-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`).
+
+## 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.
+If you have multiple configs, they will need to be merged into 1 single one. You can see the priority order of configuration files and the manor in which they are loaded on the
+[config files documentation page](https://timothycrosley.github.io/isort/docs/configuration/config_files/).
+
+### `not_skip`
+This is the same as the `--dont-skip` CLI option above. In an earlier version isort had a default skip of `__init__.py`. To get around that many projects wanted a way to not skip `__init__.py` or any other files that were automatically skipped in the future by isort. isort no longer has any default skips, so if the value here is `__init__.py` you can simply remove the setting. If it is something else, just make sure you aren't specifying to skip that file somewhere else in your config.
+
+### module placement changes: `known_third_party`, `known_first_party`, `default_section`, etc...
+isort has completely rewritten its logic for placing modules in 5.0.0 to ensure the same behavior across environments. You can see the details of this change [here](https://github.com/timothycrosley/isort/issues/1147).
+The TL;DR of which is that isort has now changed from `default_section=FIRSTPARTY` to `default_section=THIRDPARTY`. If you all already setting the default section to third party, your config is probably in good shape.
+If not, you can either use the old finding approach with `--magic-placement` in the CLI or `old_finders=True` in your config, or preferably, you are able to remove all placement options and isort will determine it correctly.
+If it doesn't, you should be able to just specify your projects modules with `known_first_party` and be done with it.