Add upgrade guide

.editorconfig

@@ -9,7 +9,6 @@ known_third_party = kate
 ignore_frosted_errors = E103
 skip = build,.tox,venv
 balanced_wrapping = true
-not_skip = __init__.py
 
 [*.{rst,ini}]
 indent_style = space

CHANGELOG.md

@@ -3,6 +3,10 @@ Changelog
 
 NOTE: isort follows the [semver](https://semver.org/) versioning standard.
 
+### 5.0.4 July 6, 2020
+  - Fixed #1264: a regression with comment handling and `force_sort_within_sections` config option
+  - Added warning for deprecated CLI flags and linked to upgrade guide.
+
 ### 5.0.3 - July 4, 2020
   - Fixed setup.py command incorrectly passing check=True as a configuration parameter (see: https://github.com/timothycrosley/isort/issues/1258)
   - Fixed missing patch version
@@ -22,7 +26,7 @@ NOTE: isort follows the [semver](https://semver.org/) versioning standard.
   - isort deprecates official support for Python 3.4, removing modules only in this release from known_standard_library:
       - user
   - Config files are no longer composed on-top of each-other. Instead the first config file found is used.
-    - Since there is no longer composition negative form settings (such as --dont-skip) are no longer required and have been removed.
+    - Since there is no longer composition negative form settings (such as --dont-skip or it's config file variant `not_skip`) are no longer required and have been removed.
   - Two-letter shortened setting names (like `ac` for `atomic`) now require two dashes to avoid ambiguity: `--ac`.
   - For consistency with other tools `-v` now is shorthand for verbose and `-V` is shorthand for version. See Issue: #1067.
   - `length_sort_{section_name}` config usage has been deprecated. Instead `length_sort_sections` list can be used to specify a list of sections that need to be length sorted.

docs/major_releases/introducing_isort_5.md

@@ -8,6 +8,8 @@ This does mean that there may be some pain with the upgrade process, but we beli
 
 [Click here for an attempt at full changelog with a list of breaking changes.](https://timothycrosley.github.io/isort/CHANGELOG/)
 
+[Using isort 4.x.x? Click here for the isort 5.0.0 upgrade guide.](https://timothycrosley.github.io/isort/docs/upgrade_guides/5.0.0/)
+
 [Try isort 5 right now from your browser!](https://timothycrosley.github.io/isort/docs/quick_start/0.-try/)
 
 So why the massive change?

isort/main.py

@@ -401,7 +401,7 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         "--sd",
         "--section-default",
         dest="default_section",
-        help="Sets the default section for imports (by default FIRSTPARTY) options: "
+        help="Sets the default section for import options: "
         + str(sections.DEFAULT),
     )
     parser.add_argument(
@@ -564,6 +564,36 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="See isort's determined config, as well as sources of config options.",
     )
+
+    # deprecated options
+    parser.add_argument(
+        "--recursive",
+        dest="deprecated_flags",
+        action="append_const",
+        const="--recursive",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "-rc", dest="deprecated_flags", action="append_const", const="-rc", help=argparse.SUPPRESS
+    )
+    parser.add_argument(
+        "--dont-skip",
+        dest="deprecated_flags",
+        action="append_const",
+        const="--dont-skip",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "-ns", dest="deprecated_flags", action="append_const", const="-ns", help=argparse.SUPPRESS
+    )
+    parser.add_argument(
+        "--apply",
+        dest="deprecated_flags",
+        action="append_const",
+        const="-y",
+        help=argparse.SUPPRESS,
+    )
+
     return parser
 
 
@@ -642,6 +672,14 @@ def main(argv: Optional[Sequence[str]] = None, stdin: Optional[TextIOWrapper] =
     check = config_dict.pop("check", False)
     show_diff = config_dict.pop("show_diff", False)
     write_to_stdout = config_dict.pop("write_to_stdout", False)
+    deprecated_flags = config_dict.pop("deprecated_flags", False)
+
+    if deprecated_flags:
+        warn(
+            f"\n\nThe following deprecated CLI flags where used: {', '.join(deprecated_flags)}!\n"
+            "Please see the 5.0.0 upgrade guide:\n"
+            "\thttps://timothycrosley.github.io/isort/docs/upgrade_guides/5.0.0/\n",
+        )
 
     if "src_paths" in config_dict:
         config_dict["src_paths"] = {