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

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.

What's Changed

• Update templates to v0.3.0 by @llucax in #73
• Fix replay file processing by @llucax in #74
• Fix a few minor bugs by @llucax in #75
• Improve cookiecutter mkdocs configuration by @llucax in #77
• Minor fixes and improvements by @llucax in #81
• Add linting to the CI with protolint for API projects by @llucax in #84
• cookiecutter: Update SDK dependency to v0.22.0 by @llucax in #88
• Capitalize project name in title by @llucax in #89
• Add example on how to exclude files in the labeler workflow by @llucax in #92
• Add a few more default keywords by @llucax in #90
• Fix license headers by @llucax in #91
• Add template variables docs and warning about cookiecutter command by @llucax in #94
• Add golden tests for generated files by @llucax in #87
• Validate template variables and improve defaults by @llucax in #95
• Prepare v0.4.0 release by @llucax in #96

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

What's Changed

• Add dependabot config to the cookiecutter template by @leandro-lucarella-frequenz in #44
• Add issue templates, keyword labeler and PR labeler to cookiecutter by @llucax in #51
• Add CODEOWNERS file in cookiecutter by @llucax in #49
• Fix python3.11 in printed nox example by @cwasicki in #45
• Add files related to direnv to gitignore by @cwasicki in #47
• Fix some comments about creating labels by @llucax in #53
• Add --diff as a default argument for isort by @shsms in #55
• Fix escaping issues in workflows templates by @llucax in #60
• Add GitHub CI workflow by @llucax in #57
• Add CONTRIBUTING guide by @llucax in #61
• Fix and speed up the CI workflow by @llucax in #63
• Add RELEASE_NOTES to cookiecutter by @llucax in #65
• Add support to generate documentation using mkdocs by @llucax in #64
• Copy follow-up instructions to README by @cwasicki in #67
• Don't import modules into packages and fix tests by @llucax in #68
• Support migrating and updating existing projects by @llucax in #69
• Generate extra configuration files using the cookiecutter template by @llucax in #66
• Fix issues in CI and updating projects by @llucax in #70
• Fix and improve documentation and generation by @llucax in #72

New Contributors

• @llucax made their first contribution in #51
• @cwasicki made their first contribution in #45
• @shsms made their first contribution in #55

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

v0.2.0

What's Changed

• Small fixes and improvements by @leandro-lucarella-frequenz in #35
• Add repository generation via cookiecutter by @leandro-lucarella-frequenz in #39
• Add support for frequenz-api-common by @leandro-lucarella-frequenz in #42

Full Changelog: v0.1.0...v0.2.0

v0.1.0

Initial release with minimal functionality.

What's Changed

• Add a setuptools support for building proto files by @leandro-lucarella-frequenz in #1
• Miscelaneous improvements by @leandro-lucarella-frequenz in #16
• Improve and fix support for compiling protobuf files by @leandro-lucarella-frequenz in #19

New Contributors

• @leandro-lucarella-frequenz made their first contribution in #1

Full Changelog: https://github.com/frequenz-floss/frequenz-repo-config-python/commits/v0.1.0