v0.9.2

Frequenz Repository Configuration Release Notes

Bug Fixes

• Pin sybil to < 6.1

  Sybil 6.1.0 fixes a bug which we thought it was proper behavior, so
  upgrading to it would break our tests.

Full Changelog: v0.9.1...v0.9.2

v0.9.1

Frequenz Repository Configuration Release Notes

Bug Fixes

• Fix that new repositories were initialized with the previous version 0.8.0.

What's Changed

• Clear release notes by @llucax in #228
• Initialize repos to version 0.9.1 by @Marenz in #231
• Clean up release notes for 0.9.1 by @llucax in #232

Full Changelog: v0.9.0...v0.9.1

v0.9.0

Frequenz Repository Configuration Release Notes

Summary

This release brings support for pytest 8, a couple of bug fixes and many improvements to the cookiecutter template.

Upgrading

• Once you upgraded, you'll be able to upgrade to pytest 8, and indirectly to sybil 6, which includes types hints. If you do so, you should remove the mypy exception for sybil in the pyproject.toml file.

  Search for the tool.mypy.overrides section and remove the "sybil", "sybil.*" enties from the module list.

Cookiecutter template

To upgrade without regenerating the project, you can follow these steps:

• Run the following command to add the new pylint ignore rules:

  sed '/  # Checked by flake8/a\  "redefined-outer-name",\n  "unused-import",' -i pyproject.toml

• It is recommended to update this rule in your repository to use the new bypass rule for the Protect version branches ruleset that allows maintainers to force-merge.

  You can do this by re-importing the ruleset or manually:

  Go to the repository settings -> Rules -> Rulesets -> Protect version branches -> Bypass list -> Add bypass -> Select Maintain role and change the dropdown bypass rule to use Pull requests instead of Always.

• The labeler action was upgraded to 5.0.0. This needs a new configuration file.

  If you haven't diverged much from the default configuration (and you are not using exclusion rules), you can update the configuration file by running this script in the root of your repository:

  import sys
  lines = []
  state = "looking"
  with open(".github/labeler.yml", encoding="utf-8") as fin:
      for line in fin:
          if "changed-files:" in line:
              sys.stderr.write("Already fixed, aborting...\n")
              sys.exit(1)
          match state:
              case "looking":
                  if not line.startswith(("#", " ", "\t")) and line.rstrip().endswith(":"):
                      line = f"{line}  - changed-files:\n    - any-glob-to-any-file:\n"
                      state = "in-label"
              case "in-label":
                  if not line.lstrip().startswith("-"):
                      state = "looking"
                  else:
                      line = f"    {line}"
          lines.append(line)
  with open(".github/labeler.yml", "w", encoding="utf-8") as fout:
      fout.writelines(lines)

  This will update the file in place, you can inspect the changes with git diff.

• For API projects, you can manually add instructions to update the mkdocs.yml when the frequenz-api-common dependency is updated.

  awk -i inplace '/^sed s..frequenz-api-common/ { print; print "sed '"'"'s|https://frequenz-floss.github.io/frequenz-api-common/v[0-9].[0-9]/objects.inv|https://frequenz-floss.github.io/frequenz-api-common/v'"'"'${ver_minor}'"'"'/objects.inv|'"'"' -i mkdocs.yml"; next }1' CONTRIBUTING.md
  

• Run the following command to fix the test-installation CI job when using git URLs in pyproject.toml:

  patch -p1 <<'EOF'
  diff --git a/.github/containers/test-installation/Dockerfile b/.github/containers/test-installation/Dockerfile
  index 772b2ae..2494545 100644
  --- a/.github/containers/test-installation/Dockerfile
  +++ b/.github/containers/test-installation/Dockerfile
  @@ -6,7 +6,12 @@
  
   FROM --platform=${TARGETPLATFORM} python:3.11-slim
  
  -RUN python -m pip install --upgrade --no-cache-dir pip
  +RUN apt-get update -y && \
  +    apt-get install --no-install-recommends -y \
  +    git && \
  +    apt-get clean && \
  +    rm -rf /var/lib/apt/lists/* && \
  +    python -m pip install --upgrade --no-cache-dir pip
  
   COPY dist dist
   RUN pip install dist/*.whl && \
  EOF
  

• If your repository uses submodules and do cross-arch tests, you need to update the nox-cross-arch job in the .github/workflows/ci.yaml workflow and add the option submodules: true to the checkout action, for example:

  steps:
    - name: Fetch sources
      uses: actions/checkout@v4
      with:
        submodules: recursive

New Features

• Add support for pytest 8.

Cookiecutter template

• Some checks that are already performed by flake8 are now disabled in pylint to avoid double reporting.
• The repository ruleset Protect version branches has been updated to allow repository maintainers to skip protection rules in PRs.
• The labeler action was upgraded to 5.0.0, which allows for more complex matching rules.
• Instruction were added to update the mkdocs.yml when the frequenz-api-common dependency is updated.

Bug Fixes

Cookiecutter template

• Fix the test-installation CI job when dependencies in pyproject.toml contain git URLs.
• Fix cross-arch testing for respositories with submodules.

What's Changed

• Clear release notes by @llucax in #206
• Make copyright year fakable in golden tests by @llucax in #212
• Make GitHub Pages configuration more accesible by @llucax in #214
• Add a few more checks to the pylint ignore list by @llucax in #208
• Allow repository maintainers to force-merge by @llucax in #213
• Upgrade to labeler 5.0.0 by @llucax in #211
• Add missing instruction to update dependencies by @llucax in #223
• ci: Support using git for dependencies in test-installation by @Marenz in #222
• Update pytest and sybil by @Marenz in #221
• Fetch submodules when doing cross-arch tests by @llucax in #225
• Prepare release notes for v0.9.0 by @llucax in #227

Full Changelog: v0.8.0...v0.9.0

v0.8.0

Frequenz Repository Configuration Release Notes

Summary

This is a minor release with some documentation improvements, new GitHub ruleset and a few bug fixes.

Upgrading

Cookiecutter template

You can follow these steps to upgrade without regenerating the whole project, if you kept the default project structure and configuration:

• Update the frequenz-repo-config dependencies in pyproject.toml to 0.8.0.

• Run in the root directory of your project:

  sed -i '/custom_templates: templates/d' mkdocs.yml
  sed -i '/  "too-few-public-methods",/a \  "too-many-return-statements",' pyproject.toml
  find -type f -exec sed -i 's/Freqenz/Frequenz/g' {} +
  cat <<EOF >> .gitignore
  
  # Auto-generated python files from the protocol buffer compiler
  py/**/*_pb2.py
  py/**/*_pb2.pyi
  py/**/*_pb2_grpc.py
  py/**/*_pb2_grpc.pyi
  EOF

• Optionally go to the GitHub project's settings and replace branch protection rules with the new rulesets. See the new GitHub configuration guide for more details.

New Features

• New GitHub rulesets are provided with the recommended configuration to protect branches and tags.
• The documentation is restructured into a more organized, easier-to-navigate user guide.
• Documentation on how to configure the GitHub project and PyPI package is now provided.

Cookiecutter template

• The pylint check too-many-return-statements is now disabled by default.
• Generated protobuf files are now ignored by Git.

Bug Fixes

Cookiecutter template

• Fix typo: Freqenz -> Frequenz
• Fix mkdocs.yml to avoid specifying custom_templates for mkdocstrings as it is unused and is checked for existence in newer versions.
• Fix paths that are not translated properly from the python package name (#198)
• Fix outdated frequenz-repo-config dependency

What's Changed

• Clear release notes by @llucax in #175
• Fix typos Freqenz -> Frequenz by @llucax in #183
• Add repository rulesets and a docs section to configure the GitHub repository by @llucax in #192
• Restructure the home page into a user guide by @llucax in #193
• Fix outdated configuration section name by @llucax in #195
• Remove custom_templates from mkdocs.yml by @llucax in #201
• Disable the pylint check too-many-return-statements by @llucax in #200
• docs: Improve mention of cmd:skip-release-notes label by @llucax in #197
• Properly translate paths from the python package name by @llucax in #199
• Ignore files generated from proto files by @llucax in #202
• docs: Improve gh-pages initialization by @llucax in #203
• Prepare for v0.8.0 release by @llucax in #204
• Add section on configuring PyPI to the user guide by @llucax in #205

Full Changelog: v0.7.5...v0.8.0

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