diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index c36a3e40..397e53b6 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,16 +2,57 @@ ## Summary -This release fixes a bug in `mike` version sorting. +This release upgrades `mike` to 2.0.0. ## Upgrading -- `frequenz.repo.config.mkdocs.mike.`: The `sort_versions()` function now takes plain `str`s as arguments instead of `MikeVersionInfo` objects. - ### Cookiecutter template -There is no need to regenerate any templates with this release. +There is no need to re-generate the cookiecutter template for this release. Instead you can upgrade the `mike` package in your `pyproject.toml` file and add the new `alias_type: redirect` option to the `plugins.mike` key in the `mkdocs.yml` file. + +You should be able to do this by running the following commands: + +```sh +sed -i '/canonical_version: latest/ i\ alias_type: redirect' mkdocs.yml +sed -i 's/ "mike == .*",/ "mike == 2.0.0",/' pyproject.toml +``` + +Please make sure to check the diff and test if everything works as expected. After doing a `git diff` you should get something like: + +```diff +diff --git a/mkdocs.yml b/mkdocs.yml +index 3d0f82e..6adfbe8 100644 +--- a/mkdocs.yml ++++ b/mkdocs.yml +@@ -93,6 +93,7 @@ plugins: + - literate-nav: + nav_file: SUMMARY.md + - mike: ++ alias_type: redirect + canonical_version: latest + - mkdocstrings: + custom_templates: templates +diff --git a/pyproject.toml b/pyproject.toml +index 9a1604b..b183524 100644 +--- a/pyproject.toml ++++ b/pyproject.toml +@@ -47,7 +47,7 @@ dev-formatting = ["black == 23.10.1", "isort == 5.12.0"] + dev-mkdocs = [ + "black == 23.10.1", + "Markdown==3.5.1", +- "mike == 1.1.2", ++ "mike == 2.0.0", + "mkdocs-gen-files == 0.5.0", + "mkdocs-literate-nav == 0.6.1", + "mkdocs-material == 9.4.7", +``` + +If that's not the case, your `pyproject.toml` and/or `mkdocs.yml` files might have been diverged from the generated files and updated in a way that is not compatible with the upgrade. In that case you'll have to fix it manually or re-generate the templates. ## Bug Fixes -- CI / `mkdocs`: `mike` version sorting now properly sort pre-releases as older than stable releases for the same major and minor version. +- `cli.version.mike.info`: Don't fail if the version can't be determined, just emit a warning and exit succesfully. + +### Cookiecutter template + +- CI: The documentation publishing job will not fail if the version for `mike` can't be determined, it will just emit a warning and skip the publishing of the documentation website. diff --git a/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml b/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml index d0257751..9669c7e6 100644 --- a/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml +++ b/cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml @@ -97,6 +97,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml b/cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml index b5816ea8..a838e0fd 100644 --- a/cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml +++ b/cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml @@ -71,7 +71,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", diff --git a/mkdocs.yml b/mkdocs.yml index 53f744f0..1778d54b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,6 +93,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/pyproject.toml b/pyproject.toml index e6b89702..ea78413f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -77,7 +77,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", diff --git a/src/frequenz/repo/config/cli/version/mike/info.py b/src/frequenz/repo/config/cli/version/mike/info.py index 8ebbf3ff..1680ea91 100644 --- a/src/frequenz/repo/config/cli/version/mike/info.py +++ b/src/frequenz/repo/config/cli/version/mike/info.py @@ -49,7 +49,10 @@ def main() -> None: try: mike_version = mike.build_mike_version(github.get_repo_version_info()) except ValueError as error: - github.abort(f"{error}.", title="Documentation was not published") + gha.warning( + f"{error}.", title="Could not determine the version information for `mike`" + ) + return _output_gha_vars(mike_version) diff --git a/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml index e5bfaf54..67c188c9 100644 --- a/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml +++ b/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml @@ -97,6 +97,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml b/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml index 31ba6062..fe742db9 100644 --- a/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml +++ b/tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml @@ -53,7 +53,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", diff --git a/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml index 739743d2..c60af2e0 100644 --- a/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml +++ b/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml @@ -97,6 +97,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml b/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml index 97981a77..929f02b0 100644 --- a/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml +++ b/tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/pyproject.toml @@ -51,7 +51,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", diff --git a/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml index 3d9c14ce..9fad7028 100644 --- a/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml +++ b/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/mkdocs.yml @@ -97,6 +97,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml b/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml index 60457934..f54d43e7 100644 --- a/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml +++ b/tests_golden/integration/test_cookiecutter_generation/app/frequenz-app-test/pyproject.toml @@ -52,7 +52,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", diff --git a/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml index c249136e..3ab63831 100644 --- a/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml +++ b/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/mkdocs.yml @@ -97,6 +97,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/pyproject.toml b/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/pyproject.toml index 3a1a5e4f..1224dcd9 100644 --- a/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/pyproject.toml +++ b/tests_golden/integration/test_cookiecutter_generation/lib/frequenz-test-python/pyproject.toml @@ -49,7 +49,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4", diff --git a/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml b/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml index f84f0f29..614d2ef2 100644 --- a/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml +++ b/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/mkdocs.yml @@ -97,6 +97,7 @@ plugins: - literate-nav: nav_file: SUMMARY.md - mike: + alias_type: redirect canonical_version: latest - mkdocstrings: custom_templates: templates diff --git a/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/pyproject.toml b/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/pyproject.toml index fb8a2502..0eb401c8 100644 --- a/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/pyproject.toml +++ b/tests_golden/integration/test_cookiecutter_generation/model/frequenz-model-test/pyproject.toml @@ -53,7 +53,7 @@ dev-formatting = ["black == 23.9.1", "isort == 5.12.0"] dev-mkdocs = [ "black == 23.9.1", "Markdown==3.4.4", - "mike == 1.1.2", + "mike == 2.0.0", "mkdocs-gen-files == 0.5.0", "mkdocs-literate-nav == 0.6.1", "mkdocs-macros-plugin == 1.0.4",