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

v0.5.2

Frequenz Repository Configuration Release Notes

Summary

This version focus on some bug fixes and final polishing of v0.5.x.

Upgrading

Cookiecutter template

• If your replay file contains a _extensions key, you should remove it, as you most likely want to use the extensions declared by the repo-config cookiecutter template you are upgrading to, otherwise you could get errors about missing extensions.

• If your replay file contains a long Introduction key, you can replace it with an empty string (""), it doesn't need to have any particular content and it increases the size and noise in the replay file.

New Features

Cookiecutter template

• Generated project's dependencies were bumped.

• Move TODOs so they are in their own line.

  This makes it easier to upgrade projects to new templates, as removing whole lines is easier than having to edit them.

• Clean up _extensions from the generated replay file.

  It is not needed in the generated project, we always want to use the ones from the repo-config template.

  This should ease upgrading projects, making it less likely to have errors about missing extensions.

• Clean up the Introduction variable from the generated replay file.

  This is just a hack to be able to show a help about the template variables, keeping that text only increases the size and noise in the replay file.

• Add a \n to the end of the replay file.

  This is just to be nice to most editors and text files conventions, that likes it more if there is a \n at the end of the file.

• API: The common-api documentation now is cross-linked.

Bug Fixes

Cookiecutter template

• Properly label conftest.py files.

What's Changed

• Clear release notes by @llucax in #117
• Bump repo-config and template dependencies by @llucax in #119
• Move TODOs so they are easier to remove by @llucax in #120
• Properly label conftest.py files by @llucax in #121
• Remove obsolete extension and clean up replay file extensions by @llucax in #118
• API: Add cross-linking to common-api and prepare for the release by @llucax in #122

Full Changelog: v0.5.1...v0.5.2

v0.5.1

Frequenz Repository Configuration Release Notes

Bug Fixes

• Fix outdated version number in the migrating and upgrading documentation.

What's Changed

• Fix version number in docs and prepare new release by @llucax in #116

Full Changelog: v0.5.0...v0.5.1

v0.5.0

Frequenz Repository Configuration Release Notes

Summary

This release adds linting of code examples in docstrings, a workflow to check if PRs have updated the release notes and an editorconfig file, as well as a bunch of bug fixes.

Upgrading

• nox: Now the default configuration for API repositories will not automatically add pytests as an extra_path

  The pytests directory is not a standard directory that will be auto-discovered by pytest, so it should always be included in the pyproject.toml file, in the tool.pytest.ini_options.testpaths array. Please check your API project is properly configured.

Cookiecutter template

• To make the new workflow to check if release notes were updated you should add the check to the branch protection rules of your repository to require this check to pass. You should also add a new label "cmd:skip-release-notes" to be able to override the check. You can use the following script to do it:

  repo=...  # org/repo
  token=... # GitHub token with the correct permissions
  name="cmd:skip-release-notes"
  desc="It is not necessary to update release notes for this PR"
  color="930F79"
  
  # Using cURL
  curl -L \
      -X POST \
      -H "Accept: application/vnd.github+json" \
      -H "Authorization: Bearer $token" \
      -H "X-GitHub-Api-Version: 2022-11-28" \
      -d '{"name":"'"$name"'","description":"'"$desc"'","color":"'"$color"'"}' \
      "https://api.github.com/repos/$repo/labels"
  
  # Using the gh tool (no need for a token if you already have it configured)
  gh api -X POST \
      -f name="$name" -f description="$desc" -f color="$color" \
      "repos/$repo/labels"

New Features

• Add support for linting code examples found in docstrings.

  A new module frequenz.repo.config.pytest.examples is added with an utility function to be able to easily collect and lint code examples in docstrings.

  There is also a new optional dependency extra-lint-examples to easily pull the dependencies needed to do this linting. Please have a look at the documentation in the frequenz.repo.config package for more details.

Cookiecutter template

• Add a new GitHub workflow to check that release notes were updated.

  This workflow will check PRs to see if a change was done in the src/ directory, and if so, it will fail if the RELEASE_NOTES.md wasn't also updated.

  Users can override this by assigning the label cmd:skip-release-notes to the PR for changes that don't really need a release notes update.

• Add MANIFEST.in file.

  This makes sure that we don't ship useless files when building the distribution package and that we include all the relevant files too, like generated *.pyi files for API repositories.

• Add an .editorconfig file to ensure a common basic editor configuration for different file types.

• Add a pytest hook to collect and lint code examples found in docstrings using pylint.

  Examples found in code docstrings in the src/ directory will now be collected and checked using pylint. This is done via the file src/conftest.py, which hooks into pytest, so to only check the examples you can run pylint src.

  Warning: There is a bug in the library used to extract the examples that prevents from collecting examples from __init__.py files. See #113 for more details.

Bug Fixes

• The distribution package doesn't include tests and other useless files anymore.

• nox

  • When discovering path extra paths, now paths will not be added if they are also source paths, as we don't want any duplicates.

  • Fix copying of Config and CommandOptions objects.

Cookiecutter template

• Now the CI workflow will checkout the submodules.

• Fix adding of an empty keyword.

• Don't distribute development files in the source distribution.

What's Changed

• Fix minor issues and improve docs by @llucax in #97
• Allow '@' in dependency string by @Marenz in #98
• Fix protobuf config by @llucax in #101
• Fix typo by @llucax in #100
• Add more information about how mike works by @llucax in #102
• Clarify that upgrading notes should be read before updating by @llucax in #103
• ci: Checkout submodules by @llucax in #106
• cookicutter: Remove trailing space from release notes by @llucax in #105
• Add workflow to check for release notes update by @llucax in #107
• Add MANIFEST.in file by @llucax in #110
• Fix release notes check for API repos by @llucax in #112
• Add cookiecutter sections to RELEASE_NOTES.md by @llucax in #111
• Add editorconfig support by @llucax in #108
• Fix several bugs by @llucax in #114
• Add linting of code examples in docstrings by @llucax in #115

New Contributors

• @Marenz made their first contribution in #98

Full Changelog: v0.4.0...v0.5.0