Migrate to use repo-config (#124)

- Migrate to use repo-config
- Fix some typing issues in src/conftest.py
- Clear release notes

Author: llucax

.cookiecutter-replay.json

@@ -0,0 +1,28 @@
+{
+  "cookiecutter": {
+    "type": "lib",
+    "name": "channels",
+    "description": "Channel implementations for Python",
+    "title": "Frequenz channels",
+    "keywords": "channel",
+    "github_org": "frequenz-floss",
+    "license": "MIT",
+    "author_name": "Frequenz Energy-as-a-Service GmbH",
+    "author_email": "[email protected]",
+    "python_package": "frequenz.channels",
+    "pypi_package_name": "frequenz-channels",
+    "github_repo_name": "frequenz-channels-python",
+    "default_codeowners": "@frequenz-floss/python-sdk-team",
+    "_extensions": [
+      "jinja2_time.TimeExtension",
+      "local_extensions.default_codeowners",
+      "local_extensions.github_repo_name",
+      "local_extensions.keywords",
+      "local_extensions.pypi_package_name",
+      "local_extensions.python_package",
+      "local_extensions.src_path",
+      "local_extensions.title"
+    ],
+    "_template": "gh:frequenz-floss/frequenz-repo-config-python"
+  }
+}

.github/ISSUE_TEMPLATE/bug.yml

@@ -5,7 +5,9 @@ name: Report something is not working properly 🐛
 description:
   Use this if there is something that is not working properly.  If you are not
   sure or you need help making something work, please ask a question instead.
-labels: priority:❓, type:bug
+labels:
+  - "priority:❓"
+  - "type:bug"
 body:
   - type: markdown
     attributes:
@@ -59,6 +61,6 @@ body:
       label: Extra information
       description:
         Please write here any extra information you think it might be relevant,
-        e.g., if this didn't happened before, or if you suspect where the
-        problem might be.
+        e.g., if this didn't happen before, or if you suspect where the problem
+        might be.
       placeholder: Any extra information you think it might be relevant.

.github/ISSUE_TEMPLATE/feature.yml

@@ -3,7 +3,10 @@
 
 name: Request a feature or enhancement ✨
 description: Use this if something is missing or could be done better or more easily.
-labels: part:❓, priority:❓, type:enhancement
+labels:
+  - "part:❓"
+  - "priority:❓"
+  - "type:enhancement"
 body:
   - type: markdown
     attributes:

.github/RELEASE_NOTES.template.md

@@ -1,12 +1,12 @@
-# Frequenz Channels Release Notes
+# Frequenz channels Release Notes
 
 ## Summary
 
 <!-- Here goes a general summary of what this release is about -->
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including if there are any deprecations and what they should be replaced with -->
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 

.github/labeler.yml

@@ -9,6 +9,7 @@
 "part:docs": 
   - "**/*.md"
   - "docs/**"
+  - "examples/**"
   - LICENSE
 
 "part:tests":
@@ -18,14 +19,13 @@
   - "**/*.ini"
   - "**/*.toml"
   - "**/*.yaml"
-  - "*requirements*.txt"
+  - "**/*.yml"
   - ".git*"
   - ".git*/**"
+  - docs/*.py
   - CODEOWNERS
   - MANIFEST.in
-  - docs/mkdocstrings_autoapi.py
   - noxfile.py
-  - setup.py
 
 "part:channels":
   - any:

.github/workflows/ci.yaml

@@ -1,9 +1,11 @@
-name: frequenz-channels-python
+name: CI
 
 on:
   merge_group:
   pull_request:
   push:
+    # We need to explicitly include tags because otherwise when adding
+    # `branches-ignore` it will only trigger on branches.
     tags:
       - '*'
     branches-ignore:
@@ -14,44 +16,47 @@ on:
   workflow_dispatch:
 
 env:
-  DEFAULT_PYTHON_VERSION: "3.11"
+  # Please make sure this version is included in the `matrix`, as the
+  # `matrix` section can't use `env`, so it must be entered manually
+  DEFAULT_PYTHON_VERSION: '3.11'
+  # It would be nice to be able to also define a DEFAULT_UBUNTU_VERSION
+  # but sadly `env` can't be used either in `runs-on`.
 
 jobs:
-  test:
+  nox:
+    name: Test with nox
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-20.04
-        python-version:
+        python:
           - "3.11"
     runs-on: ${{ matrix.os }}
 
     steps:
-    - name: Fetch sources
-      uses: actions/checkout@v3
-
-    - name: Set up Python
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ matrix.python-version }}
-
-    - uses: actions/cache@v3
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-${{ matrix.python-version }}-pip-${{ hashFiles('pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-${{ matrix.python-version }}-pip-
-
-    - name: Install required Python packages
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install nox
-
-    - name: run nox
-      run: nox
-      timeout-minutes: 10
-
-  build-dist:
+      - name: Fetch sources
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+          cache: 'pip'
+
+      - name: Install required Python packages
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev-noxfile]
+
+      - name: Run nox
+        # To speed things up a bit we use the speciall ci_checks_max session
+        # that uses the same venv to run multiple linting sessions
+        run: nox -e ci_checks_max pytest_min
+        timeout-minutes: 10
+
+  build:
+    name: Build distribution packages
     runs-on: ubuntu-20.04
     steps:
       - name: Fetch sources
@@ -61,23 +66,25 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+          cache: 'pip'
 
-      - name: Install build dependencies
+      - name: Install required Python packages
         run: |
           python -m pip install -U pip
           python -m pip install -U build
 
       - name: Build the source and binary distribution
         run: python -m build
 
-      - name: Upload dist files
+      - name: Upload distribution files
         uses: actions/upload-artifact@v3
         with:
-          name: frequenz-channels-python-dist
+          name: dist-packages
           path: dist/
           if-no-files-found: error
 
-  test-generate-docs:
+  test-docs:
+    name: Test documentation website generation
     if: github.event_name != 'push'
     runs-on: ubuntu-20.04
     steps:
@@ -91,11 +98,12 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+          cache: 'pip'
 
       - name: Install build dependencies
         run: |
           python -m pip install -U pip
-          python -m pip install .[docs]
+          python -m pip install .[dev-mkdocs]
 
       - name: Generate the documentation
         env:
@@ -107,12 +115,13 @@ jobs:
       - name: Upload site
         uses: actions/upload-artifact@v3
         with:
-          name: frequenz-channels-python-site
+          name: docs-site
           path: site/
           if-no-files-found: error
 
   publish-docs:
-    needs: ["test", "build-dist"]
+    name: Publish documentation website to GitHub pages
+    needs: ["nox", "build"]
     if: github.event_name == 'push'
     runs-on: ubuntu-20.04
     permissions:
@@ -168,12 +177,13 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+          cache: 'pip'
 
       - name: Install build dependencies
         if: steps.mike-metadata.outputs.version
         run: |
           python -m pip install -U pip
-          python -m pip install .[docs]
+          python -m pip install .[dev-mkdocs]
 
       - name: Fetch the gh-pages branch
         if: steps.mike-metadata.outputs.version
@@ -188,20 +198,21 @@ jobs:
           mike deploy --push --update-aliases "$VERSION" $ALIASES
 
   create-github-release:
+    name: Create GitHub release
     needs: ["publish-docs"]
     # Create a release only on tags creation
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     permissions:
       # We need write permissions on contents to create GitHub releases and on
       # discussions to create the release announcement in the discussion forums
       contents: write
       discussions: write
     runs-on: ubuntu-20.04
     steps:
-      - name: Download dist files
+      - name: Download distribution files
         uses: actions/download-artifact@v3
         with:
-          name: frequenz-channels-python-dist
+          name: dist-packages
           path: dist
 
       - name: Download RELEASE_NOTES.md
@@ -225,7 +236,6 @@ jobs:
           if echo "$REF_NAME" | grep -- -; then extra_opts=" --prerelease"; fi
           gh release create \
             -R "$REPOSITORY" \
-            --discussion-category announcements \
             --notes-file RELEASE_NOTES.md \
             --generate-notes \
             $extra_opts \
@@ -237,17 +247,18 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   publish-to-pypi:
+    name: Publish packages to PyPI
     needs: ["create-github-release"]
     runs-on: ubuntu-20.04
     permissions:
       # For trusted publishing. See:
       # https://blog.pypi.org/posts/2023-04-20-introducing-trusted-publishers/
       id-token: write
     steps:
-      - name: Download dist files
+      - name: Download distribution files
         uses: actions/download-artifact@v3
         with:
-          name: frequenz-channels-python-dist
+          name: dist-packages
           path: dist
 
       - name: Publish the Python distribution to PyPI

.github/workflows/labeler.yml

@@ -1,13 +1,5 @@
 name: Pull Request Labeler
 
-# XXX: !!! SECURITY WARNING !!!
-# pull_request_target has write access to the repo, and can read secrets. We
-# need to audit any external actions executed in this workflow and make sure no
-# checked out code is run (not even installing dependencies, as installing
-# dependencies usually can execute pre/post-install scripts). We should also
-# only use hashes to pick the action to execute (instead of tags or branches).
-# For more details read:
-# https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
 on: [pull_request_target]
 
 jobs:
@@ -18,7 +10,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Labeler
-        # Only use hashes, see the security comment above
+        # XXX: !!! SECURITY WARNING !!!
+        # pull_request_target has write access to the repo, and can read secrets. We
+        # need to audit any external actions executed in this workflow and make sure no
+        # checked out code is run (not even installing dependencies, as installing
+        # dependencies usually can execute pre/post-install scripts). We should also
+        # only use hashes to pick the action to execute (instead of tags or branches).
+        # For more details read:
+        # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
         uses: actions/labeler@0967ca812e7fdc8f5f71402a1b486d5bd061fe20  # 4.2.0
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"