Add support and bump to mike 2.0.0 (#174)

This PR upgrades `mike` to 2.0.0. This new version uses symlinks for
aliases by default, but they are not supported by GitHub Pages, so we
need to use the `redirect` alias type instead explicitly.

We use the new `alias_type` option in the `mike` plugin configuration in
the `mkdocs.yml` file to set the alias type to `redirect`.

It also avoid failing the documentation publishing job if the `mike`
version can't be determined (for example if the branch name is not
recognized). It will just emit a warning and skip the publishing.

Fixes #173.

Author: llucax

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.

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

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",

mkdocs.yml

@@ -93,6 +93,7 @@ plugins:
   - literate-nav:
       nav_file: SUMMARY.md
   - mike:
+      alias_type: redirect
       canonical_version: latest
   - mkdocstrings:
       custom_templates: templates

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",

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)
 

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

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",

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

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",