Repository: facebookresearch/hydra

Issue:
[Bug] Link to upgrade guide documentation site still crashes
# 🐛 Bug
## Description
In hydra-core==1.2.0, basic_launcher produces the following warning:
`Hydra versions will no longer change working directory at job runtime by default.`, but the provided website link doesn't work.

**Stack trace/error message**
```
@hydra.main(config_path="../../../configs", config_name="asr_benchmark")
/home/dantremonti/anaconda3/envs/mark-09-02/lib/python3.8/site-packages/hydra/_internal/hydra.py:119: UserWarning: Future Hydra versions will no longer change working directory at job runtime by default.
See https://hydra.cc/docs/next/upgrades/1.1_to_1.2/changes_to_job_working_dir/ for more information.
```
The provided URL, https://hydra.cc/docs/next/upgrades/1.1_to_1.2/changes_to_job_working_dir/ , leads to a crash in the docs site.
This is similar to the bug addressed in the issue: #2158

Although, the link: https://hydra.cc/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir/ works!


Discussion:

Patch:
diff --git a/hydra/_internal/config_loader_impl.py b/hydra/_internal/config_loader_impl.py
--- a/hydra/_internal/config_loader_impl.py
+++ b/hydra/_internal/config_loader_impl.py
@@ -419,7 +419,7 @@ def _load_single_config(
 
             if schema is not None:
                 try:
-                    url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/automatic_schema_matching"
+                    url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/automatic_schema_matching"
                     if "defaults" in schema.config:
                         raise ConfigCompositionException(
                             dedent(
diff --git a/hydra/_internal/config_repository.py b/hydra/_internal/config_repository.py
--- a/hydra/_internal/config_repository.py
+++ b/hydra/_internal/config_repository.py
@@ -178,7 +178,7 @@ def _create_defaults_list(
     ) -> List[InputDefault]:
         def issue_deprecated_name_warning() -> None:
             # DEPRECATED: remove in 1.2
-            url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_package_header"
+            url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_package_header"
             deprecation_warning(
                 message=dedent(
                     f"""\
diff --git a/hydra/_internal/core_plugins/zsh_completion.py b/hydra/_internal/core_plugins/zsh_completion.py
--- a/hydra/_internal/core_plugins/zsh_completion.py
+++ b/hydra/_internal/core_plugins/zsh_completion.py
@@ -33,7 +33,7 @@ def help(command: str) -> str:
         assert command in ["install", "uninstall"]
         extra_description = (
             "Zsh is compatible with the Bash shell completion, see the [documentation]"
-            "(https://hydra.cc/docs/next/tutorials/basic/running_your_app/tab_completion#zsh-instructions)"
+            "(https://hydra.cc/docs/tutorials/basic/running_your_app/tab_completion#zsh-instructions)"
             " for details.\n    "
         )
         command_text = f'eval "$({{}} -sc {command}=bash)"'
diff --git a/hydra/_internal/defaults_list.py b/hydra/_internal/defaults_list.py
--- a/hydra/_internal/defaults_list.py
+++ b/hydra/_internal/defaults_list.py
@@ -404,7 +404,7 @@ def _update_overrides(
         if isinstance(d, GroupDefault):
             if legacy_hydra_override:
                 d.override = True
-                url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/defaults_list_override"
+                url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/defaults_list_override"
                 msg = dedent(
                     f"""\
                     In {parent.get_config_path()}: Invalid overriding of {d.group}:
diff --git a/hydra/core/default_element.py b/hydra/core/default_element.py
--- a/hydra/core/default_element.py
+++ b/hydra/core/default_element.py
@@ -120,7 +120,7 @@ def set_package_header(self, package_header: Optional[str]) -> None:
         if not version.base_at_least("1.2"):
             if "_group_" in package_header or "_name_" in package_header:
                 path = self.get_config_path()
-                url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_package_header"
+                url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_package_header"
                 deprecation_warning(
                     message=dedent(
                         f"""\
@@ -546,7 +546,7 @@ def resolve_interpolation(self, known_choices: DictConfig) -> None:
                 msg = dedent(
                     f"""
 Defaults list element '{self.get_override_key()}={name}' is using a deprecated interpolation form.
-See http://hydra.cc/docs/next/upgrades/1.0_to_1.1/defaults_list_interpolation for migration information."""
+See http://hydra.cc/docs/1.1/upgrades/1.0_to_1.1/defaults_list_interpolation for migration information."""
                 )
                 if not version.base_at_least("1.2"):
                     deprecation_warning(
diff --git a/hydra/core/override_parser/overrides_parser.py b/hydra/core/override_parser/overrides_parser.py
--- a/hydra/core/override_parser/overrides_parser.py
+++ b/hydra/core/override_parser/overrides_parser.py
@@ -96,7 +96,7 @@ def parse_overrides(self, overrides: List[str]) -> List[Override]:
                 raise OverrideParseException(
                     override=override,
                     message=f"{msg}"
-                    f"\nSee https://hydra.cc/docs/next/advanced/override_grammar/basic for details",
+                    f"\nSee https://hydra.cc/docs/advanced/override_grammar/basic for details",
                 ) from e.__cause__
             assert isinstance(parsed, Override)
             parsed.config_loader = self.config_loader
diff --git a/hydra/core/override_parser/types.py b/hydra/core/override_parser/types.py
--- a/hydra/core/override_parser/types.py
+++ b/hydra/core/override_parser/types.py
@@ -485,7 +485,7 @@ def get_value_element_as_str(self, space_after_sep: bool = False) -> str:
     def validate(self) -> None:
         if not version.base_at_least("1.2"):
             if self.package is not None and "_name_" in self.package:
-                url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_package_header"
+                url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_package_header"
                 deprecation_warning(
                     message=dedent(
                         f"""\
diff --git a/hydra/core/utils.py b/hydra/core/utils.py
--- a/hydra/core/utils.py
+++ b/hydra/core/utils.py
@@ -152,7 +152,9 @@ def run_job(
                 _chdir = False
 
         if _chdir is None:
-            url = "https://hydra.cc/docs/next/upgrades/1.1_to_1.2/changes_to_job_working_dir/"
+            url = (
+                "https://hydra.cc/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir/"
+            )
             deprecation_warning(
                 message=dedent(
                     f"""\
@@ -287,7 +289,7 @@ def validate_config_path(config_path: Optional[str]) -> None:
             msg = dedent(
                 """\
             Using config_path to specify the config name is not supported, specify the config name via config_name.
-            See https://hydra.cc/docs/next/upgrades/0.11_to_1.0/config_path_changes
+            See https://hydra.cc/docs/upgrades/0.11_to_1.0/config_path_changes
             """
             )
             raise ValueError(msg)
diff --git a/hydra/initialize.py b/hydra/initialize.py
--- a/hydra/initialize.py
+++ b/hydra/initialize.py
@@ -65,7 +65,7 @@ def __init__(
             if version.base_at_least("1.2"):
                 config_path = None
             elif version_base is _UNSPECIFIED_:
-                url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"
+                url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"
                 deprecation_warning(
                     message=dedent(
                         f"""\
diff --git a/hydra/main.py b/hydra/main.py
--- a/hydra/main.py
+++ b/hydra/main.py
@@ -59,7 +59,7 @@ def main(
         if version.base_at_least("1.2"):
             config_path = None
         elif version_base is _UNSPECIFIED_:
-            url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"
+            url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path"
             deprecation_warning(
                 message=dedent(
                     f"""
diff --git a/plugins/hydra_optuna_sweeper/hydra_plugins/hydra_optuna_sweeper/_impl.py b/plugins/hydra_optuna_sweeper/hydra_plugins/hydra_optuna_sweeper/_impl.py
--- a/plugins/hydra_optuna_sweeper/hydra_plugins/hydra_optuna_sweeper/_impl.py
+++ b/plugins/hydra_optuna_sweeper/hydra_plugins/hydra_optuna_sweeper/_impl.py
@@ -180,9 +180,7 @@ def __init__(
         self.search_space_distributions: Optional[Dict[str, BaseDistribution]] = None
 
     def _process_searchspace_config(self) -> None:
-        url = (
-            "https://hydra.cc/docs/next/upgrades/1.1_to_1.2/changes_to_sweeper_config/"
-        )
+        url = "https://hydra.cc/docs/upgrades/1.1_to_1.2/changes_to_sweeper_config/"
         if self.params is None and self.search_space is None:
             self.params = OmegaConf.create({})
         elif self.search_space is not None:


Test patch:
diff --git a/tests/defaults_list/test_defaults_list.py b/tests/defaults_list/test_defaults_list.py
--- a/tests/defaults_list/test_defaults_list.py
+++ b/tests/defaults_list/test_defaults_list.py
@@ -910,7 +910,7 @@ def test_include_nested_group_name_(
     expected: List[ResultDefault],
     warning_file: str,
 ) -> None:
-    url = "https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_package_header"
+    url = "https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_package_header"
     msg = f"In {warning_file}: Defaults List contains deprecated keyword _name_, see {url}\n"
 
     with warns(UserWarning, match=re.escape(msg)):
diff --git a/tests/defaults_list/test_defaults_tree.py b/tests/defaults_list/test_defaults_tree.py
--- a/tests/defaults_list/test_defaults_tree.py
+++ b/tests/defaults_list/test_defaults_tree.py
@@ -946,7 +946,7 @@ def test_legacy_override_hydra_version_base_1_1(
         """\
         Invalid overriding of hydra/help:
         Default list overrides requires 'override' keyword.
-        See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/defaults_list_override for more information."""
+        See https://hydra.cc/docs/upgrades/1.0_to_1.1/defaults_list_override for more information."""
     )
     with warns(expected_warning=UserWarning, match=re.escape(msg)):
         _test_defaults_tree_impl(
@@ -2024,7 +2024,7 @@ def test_legacy_interpolation(
     msg = dedent(
         """
     Defaults list element '.*=.*' is using a deprecated interpolation form.
-    See http://hydra.cc/docs/next/upgrades/1.0_to_1.1/defaults_list_interpolation for migration information."""
+    See http://hydra.cc/docs/1.1/upgrades/1.0_to_1.1/defaults_list_interpolation for migration information."""
     )
     version.setbase("1.1")
     with warns(expected_warning=UserWarning, match=msg):
@@ -2839,7 +2839,7 @@ def test_deprecated_package_header_keywords(
     msg = dedent(
         f"""\
         In '{config_name}': Usage of deprecated keyword in package header '# @package {package_header}'.
-        See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_package_header for more information"""
+        See https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_package_header for more information"""
     )
 
     version.setbase("1.1")
diff --git a/tests/test_compose.py b/tests/test_compose.py
--- a/tests/test_compose.py
+++ b/tests/test_compose.py
@@ -730,7 +730,7 @@ def test_initialize_without_config_path(tmpdir: Path) -> None:
     expected = dedent(
         """\
         config_path is not specified in hydra.initialize().
-        See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path for more information."""
+        See https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path for more information."""
     )
     with warns(expected_warning=UserWarning, match=re.escape(expected)):
         with initialize():
diff --git a/tests/test_config_loader.py b/tests/test_config_loader.py
--- a/tests/test_config_loader.py
+++ b/tests/test_config_loader.py
@@ -293,7 +293,7 @@ def test_load_config_file_with_schema_validation(
             """\
           'config' is validated against ConfigStore schema with the same name.
           This behavior is deprecated in Hydra 1.1 and will be removed in Hydra 1.2.
-          See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/automatic_schema_matching for migration instructions."""
+          See https://hydra.cc/docs/upgrades/1.0_to_1.1/automatic_schema_matching for migration instructions."""
         )
         with warns(UserWarning, match=re.escape(msg)):
             cfg = config_loader.load_configuration(
diff --git a/tests/test_hydra.py b/tests/test_hydra.py
--- a/tests/test_hydra.py
+++ b/tests/test_hydra.py
@@ -192,7 +192,7 @@ def test_app_with_config_path_backward_compatibility(
     msg = dedent(
         """\
     Using config_path to specify the config name is not supported, specify the config name via config_name.
-    See https://hydra.cc/docs/next/upgrades/0.11_to_1.0/config_path_changes
+    See https://hydra.cc/docs/upgrades/0.11_to_1.0/config_path_changes
     """
     )
 
@@ -754,7 +754,7 @@ def test_sweep_complex_defaults(
 
                     Zsh - Install:
                     Zsh is compatible with the Bash shell completion, see the [documentation]\
-(https://hydra.cc/docs/next/tutorials/basic/running_your_app/tab_completion#zsh-instructions) \
+(https://hydra.cc/docs/tutorials/basic/running_your_app/tab_completion#zsh-instructions) \
 for details.
                     eval "$(python {script} -sc install=bash)"
                     Zsh - Uninstall:
@@ -812,7 +812,7 @@ def test_sweep_complex_defaults(
 
                     Zsh - Install:
                     Zsh is compatible with the Bash shell completion, see the [documentation]\
-(https://hydra.cc/docs/next/tutorials/basic/running_your_app/tab_completion#zsh-instructions) \
+(https://hydra.cc/docs/tutorials/basic/running_your_app/tab_completion#zsh-instructions) \
 for details.
                     eval "$(python {script} -sc install=bash)"
                     Zsh - Uninstall:
@@ -1486,7 +1486,7 @@ def test_hydra_main_without_config_path(tmpdir: Path) -> None:
           @hydra.main()
         .*my_app.py:7: UserWarning:
         config_path is not specified in @hydra.main().
-        See https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path for more information.
+        See https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_hydra_main_config_path for more information.
           @hydra.main()
         """
     )
@@ -1508,7 +1508,7 @@ def test_job_chdir_not_specified(tmpdir: Path) -> None:
     expected = dedent(
         """
         .*UserWarning: Future Hydra versions will no longer change working directory at job runtime by default.
-        See https://hydra.cc/docs/next/upgrades/1.1_to_1.2/changes_to_job_working_dir/ for more information..*
+        See https://hydra.cc/docs/upgrades/1.1_to_1.2/changes_to_job_working_dir/ for more information..*
         .*
         """
     )
diff --git a/tests/test_hydra_cli_errors.py b/tests/test_hydra_cli_errors.py
--- a/tests/test_hydra_cli_errors.py
+++ b/tests/test_hydra_cli_errors.py
@@ -44,7 +44,7 @@
             ["+key=choice(choice(a,b))", "-m"],
             """Error parsing override '+key=choice(choice(a,b))'
 ValueError while evaluating 'choice(choice(a,b))': nesting choices is not supported
-See https://hydra.cc/docs/next/advanced/override_grammar/basic for details
+See https://hydra.cc/docs/advanced/override_grammar/basic for details
 
 Set the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.
 """,
diff --git a/tests/test_overrides_parser.py b/tests/test_overrides_parser.py
--- a/tests/test_overrides_parser.py
+++ b/tests/test_overrides_parser.py
@@ -996,7 +996,7 @@ def test_override(
 def test_deprecated_name_package(hydra_restore_singletons: Any) -> None:
     msg = (
         "In override key@_name_=value: _name_ keyword is deprecated in packages, "
-        "see https://hydra.cc/docs/next/upgrades/1.0_to_1.1/changes_to_package_header"
+        "see https://hydra.cc/docs/upgrades/1.0_to_1.1/changes_to_package_header"
     )
 
     version.setbase("1.1")