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.

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.

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.

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.

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.

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.

  !!! info

  There is a bug in the library used to extract the examples that prevents from collecting examples from `__init__.py` files. See https://github.com/frequenz-floss/frequenz-repo-config-python/issues/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.

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

v0.4.0

Frequenz Repository Configuration Release Notes

Summary

This release only ships fixes and improvements for Cookiecutter templates, it is recommended for existing projects to regenerate the templates.

Upgrading

Cookiecutter templates

• You might want to remove the _output_dir from the
  .cookiecutter-replay.json file, if there is one in your project.
• You will need to manually add local_extensions.as_identifier to the _extensions key in the .cookiecutter-replay.json file before running the replay.

New Features

Cookiecutter templates

• Add linting to the CI with protolint for API projects.

• Capitalize project name in title and expand shortened words.

• Add templates variables reference documentation in the genrated docs and when running Cookiecutter.

• Do some basic templates variables validation.

• labeler workflow configuration

  • Label docs/*.py as tooling.
  • Add example on how to exclude files.

• pyproject.toml

  • Bump SDK version to v0.22.0.
  • Disable pylint's unsubscriptable-object check.
  • Add a few more default keywords.
  • Run isort in benchmarks/ too

• mkdocs

  • Add more cross-reference inventories: typing-extensions, frequenz-sdk, frequenz-channels, grpc.
  • Add some extra markdown plugins: code annotations, copy button and line numbers, keys representation.
  • Be strict when building the docs (any warning will make the generation fail).

Bug Fixes

Cookiecutter templates

• Fix hardcoded MIT license headers. Now the user selected license is used instead.

• Properly handle project names with - and _ in them.

• pyproject.toml

  • Add missing repo-config to dev-mkdocs dependencies.
  • Fix wrong optional dependency name for dev dependencies.

Full Changelog: v0.3.0...v0.4.0

v0.3.0

Frequenz Repository Configuration Release Notes

Summary

This release is a major step and adds many features and breaking changes.

Upgrading

Since this project is still in heavy development, the easiest way to upgrade is
to regenerate the templates. Please follow the instructions in the new
documentation website about updating
projects.

New Features

This is just a quick (non-comprehensive) summary of the new features:

• Add --diff as a default argument for isort

• Improve README

• Don't import modules into packages

• Support migrating and updating existing projects with Cookiecutter

• Cookiecutter template

  • Add dependabot configuration
  • Add issue templates, keyword labeler, and PR labeler
  • Add CODEOWNERS file
  • Add direnv-related files to .gitignore
  • Add GitHub CI workflow to cookiecutter
  • Add CONTRIBUTING guide to cookiecutter
  • Add RELEASE_NOTES to cookiecutter
  • Add support to generate documentation using mkdocs

• Apply all the Cookiecutter template improvements to this project

Bug Fixes

This is just a quick (non-comprehensive) summary of bug fixes:

• Fix some comments about creating labels
• Fix tests

Full Changelog: v0.2.0...v0.3.0