v0.7.5

Frequenz Repository Configuration Release Notes

Summary

This release upgrades mike to 2.0.0.

Upgrading

Cookiecutter template

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:

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

• 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.

What's Changed

• Add support and bump to mike 2.0.0 by @llucax in #174

Full Changelog: v0.7.4...v0.7.5

v0.7.4

Frequenz Repository Configuration Release Notes

Summary

This release fixes a bug in mike version sorting.

Upgrading

• frequenz.repo.config.mkdocs.mike.: The sort_versions() function now takes plain strs as arguments instead of MikeVersionInfo objects.

Cookiecutter template

There is no need to regenerate any templates with this release.

Bug Fixes

• CI / mkdocs: mike version sorting now properly sort pre-releases as older than stable releases for the same major and minor version.

What's Changed

• Fix mike version sorting by @llucax in #171

Full Changelog: v0.7.3...v0.7.4

v0.7.3

Frequenz Repository Configuration Release Notes

Summary

This release adds support for pylint 3, so downstream projects can upgrade their pylint version.

Upgrading

If upgrading pylint you might get a few new check errors.

Cookiecutter template

There is no need to regenerate any templates with this release.

Bug Fixes

• mkdocs: The conftest module is now properly hidden from the documentation again.

What's Changed

• Add support for pylint 3.0 by @llucax in #169
• docs: Hide conftest at any level by @llucax in #170

Full Changelog: v0.7.2...v0.7.3

v0.7.2

Frequenz Repository Configuration Release Notes

Upgrading

Cookiecutter template

Instead of regenerating the templates, you can simply:

• Run this command to fix the typo and wrong cli package:

  sed -i 's/annothations/annotations/' docs/_css/style.css
  sed -i 's/frequenz\.repo\.config\.cli\.version\.mkdocs\.sort/frequenz.repo.config.cli.version.mike.sort/' .github/workflows/ci.yaml

• Replace the comment after the copyright notice in .github/containers/nox-cross-arch/arm64-ubuntu-20.04-python-3.11.Dockerfile with:

  # This Dockerfile is used to run the tests in arm64, which is not supported by
  # GitHub Actions at the moment.

Bug Fixes

Cookiecutter template

• docs: Fix typo in docs/_css/style.css ("annothations" -> "annotations")
• ci: Fix the description of the arm64 Dockerfile

What's Changed

• Fix minor issues in some comments by @llucax in #167
• Clear release notes by @llucax in #166

Full Changelog: v0.7.1...v0.7.2

v0.7.1

Frequenz Repository Configuration Release Notes

New Features

Cookiecutter template

• Show a link to the documentation in PyPI.

What's Changed

• Add link to documentation on PyPI by @llucax in #164

Full Changelog: v0.7.0...v0.7.1

v0.7.0

Frequenz Repository Configuration Release Notes

Summary

This release focuses on improving the documentation generation and the CI. In particular it brings a new versioning scheme for the documentation that supports multiple development branches and exposes pre-releases.

Upgrading

Cookiecutter template

• The recommended cookiecutter version was bumped to 2.4.0 to avoid some buggy old versions.

• mkdocs

  • The script docs/mkdocstrings_autoapi.py was moved to docs/_scripts/mkdocstrings.py.

  • Note that now code annotations will be numbered. This is useful to hint about the order one should read the annotations.

  • The following files were renamed to keep the documentation directory clean for documentation files:

    • docs/css -> docs/_css
    • docs/overrides -> docs/_overrides
    • logo.png -> docs/_img/logo.png

  • You might need to remove old mike version aliases. Probably removing next should be enough:

    mike delete -p next

    You can use mike list to list all versions and aliases.

• CI

  • You can now make your branch protection rule only require the "Test with nox" CI job to pass. All the matrix expansions will merge into it, so there is no need to change branch protection rules if matrix elements are added or removed.
  • Dependabot now will check for updates monthly and on a random day and time.

• The src/conftest.py file was moved to src/<project_path>/conftest.py.

  This is to leave the src directory free of any files, so it is easier to navigate using auto-completion and GitHub file browser.

New Features

• frequenz_repo_config.version: New module to get the version information for a repository.

• frequnz_repo_config.github: New module to interact with GitHub.

• frequenz.repo_config.mkdocs.mike: New module to manage mike versions and aliases.

• frequenz.repo_config.cli: New package to implement CLI commands.

  • frequenz.repo.config.cli.version.mike.info: New command to print GitHub Action variables with for the current mike version.
  • frequenz.repo.config.cli.version.mike.sort: New command to sort mike versions file (versions.json).

Cookiecutter template

• mkdocs

  • New markdown extensions: def_list / task_list and footnotes.

  • New mkdocs-macros extension.

  • Show inherited attributes in the documentation.

  • Make code annotations numbered. This is useful to hint about the order one should read the annotations.

  • Add a navigation footer to show previous and next pages. This is specially useful when reading the documentation in a mobile device since the navigation bar is hidden.

  • Updated dependencies.

  • The hooking of mkdocstrings to macros plugins is moved to a separate function to avoid the noise in the define_env() function.

  • Improve formatting of signatures to show the types.

  • We use a new mike versioning scheme:

    • Versions now have a title with the full tag name for tags and includes the (short) commit SHA for branches so users can know exactly which version they are reading.
    • Pre-releases are now published too as vX.Y-pre. They have aliases to point to the latest pre-release in a major (vX-pre) and the absolute latest pre-release (latest-pre).
    • All branches are now published with their own version as vX.Y-dev. They have aliases to point to the latest version in a major (vX-dev) and the absolute latest version (latest-dev). This means the old next becomes latest-dev.

• CI

  • Add CI job to test package installation on multiple platforms (amd64 and arm64).
  • Add CI job to run the tests in arm64.
  • Add a CI job to join all nox runs, so only one branch protection rule needs to be used.
  • Dependabot now will check for updates monthly and on a random day and time. This is to avoid all repositories updating at the same time.

• Add a section about cross-arch testing to CONTRIBUTING.md.

Bug Fixes

Cookiecutter template

• mkdocs

  • Fixed mermaid diagrams not rendering in the documentation.
  • mypy ignores for cookiecutter have been removed. They should have never be there as generated projects don't use cookiecutter.
  • mypy overrides now are applied to API projects too.
  • Now the latest mike version will point to the highest stable version available, not the latest version published.

• Dependabot branches are now not tested for push events, as they are already tested by pull events.

What's Changed

• Clear release notes by @llucax in #139
• Several fixes and improvements by @llucax in #141
• Move cookiecutter filters to a Jinja2 extension by @llucax in #143
• Make dependabot update monthly by @llucax in #144
• Add a navigation footer to show previous and next pages by @llucax in #148
• [ci] [cross-arch] Allow creating venvs with python 3.11 by @tiyash-basu-frequenz in #151
• Don't run cookiecutter tests in arm64 by @llucax in #155
• Don't test the push event for dependabot branches by @llucax in #154
• Move src/confest.py to src/frequenz/repo/conftest.py by @llucax in #146
• Improve mike versions by @llucax in #150
• Keep versions up to date in the docs by @llucax in #162

New Contributors

• @tiyash-basu-frequenz made their first contribution in #151

Full Changelog: v0.6.2...v0.7.0

v0.7.0-rc.1

Frequenz Repository Configuration Release Notes

Summary

This release focuses on improving the documentation generation and the CI. In particular it brings a new versioning scheme for the documentation that supports multiple development branches and exposes pre-releases.

Upgrading

Cookiecutter template

• The recommended cookiecutter version was bumped to 2.4.0 to avoid some buggy old versions.

• mkdocs

  • The script docs/mkdocstrings_autoapi.py was moved to docs/_scripts/mkdocstrings.py.

  • Note that now code annotations will be numbered. This is useful to hint about the order one should read the annotations.

  • The following files were renamed to keep the documentation directory clean for documentation files:

    • docs/css -> docs/_css
    • docs/overrides -> docs/_overrides
    • logo.png -> docs/_img/logo.png

  • You might need to remove old mike version aliases. Probably removing next should be enough:

    mike delete -p next

    You can use mike list to list all versions and aliases.

• CI

  • You can now make your branch protection rule only require the "Test with nox" CI job to pass. All the matrix expansions will merge into it, so there is no need to change branch protection rules if matrix elements are added or removed.
  • Dependabot now will check for updates monthly and on a random day and time.

• The src/conftest.py file was moved to src/<project_path>/conftest.py.

  This is to leave the src directory free of any files, so it is easier to navigate using auto-completion and GitHub file browser.

New Features

• frequenz_repo_config.version: New module to get the version information for a repository.

• frequnz_repo_config.github: New module to interact with GitHub.

• frequenz.repo_config.mkdocs.mike: New module to manage mike versions and aliases.

• frequenz.repo_config.cli: New package to implement CLI commands.

  • frequenz.repo.config.cli.version.mike.info: New command to print GitHub Action variables with for the current mike version.
  • frequenz.repo.config.cli.version.mike.sort: New command to sort mike versions file (versions.json).

Cookiecutter template

• mkdocs

  • New markdown extensions: def_list / task_list and footnotes.

  • New mkdocs-macros extension.

  • Show inherited attributes in the documentation.

  • Make code annotations numbered. This is useful to hint about the order one should read the annotations.

  • Add a navigation footer to show previous and next pages. This is specially useful when reading the documentation in a mobile device since the navigation bar is hidden.

  • Updated dependencies.

  • The hooking of mkdocstrings to macros plugins is moved to a separate function to avoid the noise in the define_env() function.

  • Improve formatting of signatures to show the types.

  • We use a new mike versioning scheme:

    • Versions now have a title with the full tag name for tags and includes the (short) commit SHA for branches so users can know exactly which version they are reading.
    • Pre-releases are now published too as vX.Y-pre. They have aliases to point to the latest pre-release in a major (vX-pre) and the absolute latest pre-release (latest-pre).
    • All branches are now published with their own version as vX.Y-dev. They have aliases to point to the latest version in a major (vX-dev) and the absolute latest version (latest-dev). This means the old next becomes latest-dev.

• CI

  • Add CI job to test package installation on multiple platforms (amd64 and arm64).
  • Add CI job to run the tests in arm64.
  • Add a CI job to join all nox runs, so only one branch protection rule needs to be used.
  • Dependabot now will check for updates monthly and on a random day and time. This is to avoid all repositories updating at the same time.

• Add a section about cross-arch testing to CONTRIBUTING.md.

Bug Fixes

Cookiecutter template

• mkdocs

  • Fixed mermaid diagrams not rendering in the documentation.
  • mypy ignores for cookiecutter have been removed. They should have never be there as generated projects don't use cookiecutter.
  • mypy overrides now are applied to API projects too.
  • Now the latest mike version will point to the highest stable version available, not the latest version published.

• Dependabot branches are now not tested for push events, as they are already tested by pull events.

What's Changed

• Clear release notes by @llucax in #139
• Several fixes and improvements by @llucax in #141
• Move cookiecutter filters to a Jinja2 extension by @llucax in #143
• Make dependabot update monthly by @llucax in #144
• Add a navigation footer to show previous and next pages by @llucax in #148
• [ci] [cross-arch] Allow creating venvs with python 3.11 by @tiyash-basu-frequenz in #151
• Don't run cookiecutter tests in arm64 by @llucax in #155
• Don't test the push event for dependabot branches by @llucax in #154
• Move src/confest.py to src/frequenz/repo/conftest.py by @llucax in #146
• Improve mike versions by @llucax in #150
• Keep versions up to date in the docs by @llucax in #162

New Contributors

• @tiyash-basu-frequenz made their first contribution in #151

Full Changelog: v0.6.2...v0.7.0-rc.1

v0.6.2

Frequenz Repository Configuration Release Notes

Bug Fixes

• Update the version used in the documentation.

Cookiecutter template

• Update the generated version in dependencies.

• Exclude benchmarks/ directory from source distribution.

• Use the native navigation.indexes extension from mkdocs-material instead of the section-indexes plugin.

  The plugin had some issues when failing to keep up to date.

What's Changed

• Clear release notes by @llucax in #130
• Bug fixes for v0.6.2 by @llucax in #137

Full Changelog: v0.6.1...v0.6.2

v0.6.1

Frequenz Repository Configuration Release Notes

Bug Fixes

Cookiecutter template

• Fix typo in dependabot's configuration for grouping.

What's Changed

• Fix dependabot grouping by @llucax in #129

Full Changelog: v0.6.0...v0.6.1

v0.6.0

Frequenz Repository Configuration Release Notes

Summary

This release replaces darglint (not maintained anymore) with pydoclint which brings performance and checks improvements. It also adds basic flake8 checks and mypy fixes.

Upgrading

• flake8 basic checks are enabled now. Most are already covered by pylint, but there are a few differences, so you might need to fix your code if flake8 find some issues.

• darglint:

  • Replaced by pydoclint, pydoclint can find a few more issues than darglint, so your code might need adjusting.

  • It is recommended to remove the darglint configuration file .darglint and the darglint pip package, if it is kept installed, it will make flake8 run extremely slowly even if not used: pip uninstall darglint) and rebuild you nox venvs if you use -R.

• If you are upgrading without regenerating the cookiecutter templates, you'll need to adjust the dependencies accordingly.

• nox: The Config.package_args() method was removed.

• mypy

  • Options must be specified in the pyproject.toml file, including the option packages specifying the package containing the source code of the project. The documentation was updated to suggest the recommended options.

  • Dependencies on stubs for running the type check need to be specified manually in the pyproject.toml file, so they can be pinned (before they were installed automatically by mypy.

  • The mypy nox session runs mypy 2 times, one without options to check the package including the sources, and one with the paths of development paths (tests, benchmarks, etc.).

  To migrate existing projects:

  1. Add the recommended options (previously specified in the default options object):

     [tool.mypy]
     explicit_package_bases = true
     namespace_packages = true
     packages = ["<package.name>"]  # For example: "frequenz.repo.config" for this package
     strict = true

  2. Find out which stubs were previously installed automatically by mypy:

     python -m venv tmp_venv
     . tmp_venv/bin/activate
     pip install -e .[dev-mypy]
     mypy --install-types
     deactivate

  3. Look at the list of packages it offers to install and answer "no".

  4. Search for the latest package version for those packages in https://pypi.org/project//

  5. Edit the pyproject.toml file to add those dependencies in dev-mypy, for example:

     [project.optional-dependencies]
     dev-mypy = [
     "mypy == 1.5.1",
     "types-setuptools == 68.1.0.0",
     # ...

Cookiecutter template

• CI: The nox job now uses a matrix to run the different nox sessions in parallel. If you use branch projection with the nox job you need to update the rules to include each matrix job.

• See the general upgrading section.

New Features

• flake8 is now used to check the files.

• darlint was replaced by pydoclint, which is way faster and detect more issues.

• nox: The Config.path_args() method now accepts two optional arguments to control with paths to include.

Cookiecutter template

• Now dependabot updates will be done weekly and grouped by required and optional for minor and patch updates (major updates are still done individually for each dependency).

• ci: Add debug information when installing pip packages.

  The output of pip freeze is printed to be able to more easily debug different behaviours between GitHub workflow runs and local runs.

• mypy: Add a commented out no-incremental option, which makes the run slower but prevents some issues with mypy giving different results on different runs.

• See the general new features section.

What's Changed

• Clear release notes by @llucax in #123
• Group dependabot updates by @llucax in #126
• ci: Add env and pip debug information by @llucax in #127
• Improve comment about updating dependencies by @llucax in #125
• Replace darglint with pydoclint by @llucax in #124
• Improve how mypy is run by @llucax in #128

Full Changelog: v0.5.2...v0.6.0