Upload Packages to PyPI

.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:

.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

@@ -0,0 +1,17 @@
+# 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 deprecations and what they should be replaced with --> 
+
+## New Features
+
+<!-- Here goes the main new features and examples or instructions on how to use them -->
+
+## Bug Fixes
+
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

.github/workflows/ci.yaml

@@ -1,85 +1,132 @@
 name: frequenz-sdk-python
 
-on:
-  push:
-    branches: [ v0.x.x ]
-
-  pull_request:
-
-env:
-  REGISTRY: ghcr.io
+on: [pull_request, push, workflow_dispatch]
 
 jobs:
   test:
     strategy:
       fail-fast: false
       matrix:
-        python: [ "3.8", "3.9", "3.10" ]
-        os: [ ubuntu-20.04 ]
-
+        os:
+          - ubuntu-20.04
+        python:
+          - "3.8"
+          - "3.9"
+          - "3.10"
     runs-on: ${{ matrix.os }}
 
     steps:
       - name: Fetch sources
-        uses: actions/checkout@v2
-        with:
-          token: ${{ secrets.CI_ACCESS_TOKEN || github.token }}
-          submodules: true
+        uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
 
-      - uses: actions/cache@v2
+      - uses: actions/cache@v3
         with:
           path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/minimum-requirements-ci.txt') }}
+          key: ${{ runner.os }}-${{ matrix.python-version }}-pip-${{ hashFiles('minimum-requirements-ci.txt', 'pyproject.toml') }}
           restore-keys: |
-            ${{ runner.os }}-pip-
+            ${{ runner.os }}-${{ matrix.python-version }}-pip-
 
       - name: Install required Python packages
         run: |
           python -m pip install --upgrade pip
-          python -m pip install nox wheel
+          python -m pip install nox
 
       - name: run nox
         run: nox -e ci_checks_max pytest_min
         timeout-minutes: 10
 
-  build-wheels:
+  build-dist:
     runs-on: ubuntu-20.04
-    needs: test
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install build dependencies
+        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
+        uses: actions/upload-artifact@v3
+        with:
+          name: frequenz-sdk-python-dist
+          path: dist/
+          if-no-files-found: error
+
+  create-github-release:
+    needs: ["test", "build-dist"]
+    # Create a release only on tags creation
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    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: Fetch sources
-      uses: actions/checkout@v2
-      with:
-        token: ${{ secrets.CI_ACCESS_TOKEN || github.token }}
-        submodules: true
-
-    - name: Set up Python
-      uses: actions/setup-python@v2
-      with:
-        python-version: 3.8
-
-    - uses: actions/cache@v2
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/minimum-requirements-ci.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
-
-    - name: Install required Python packages
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install wheel
-
-    - name: make wheel
-      run: python -m pip wheel --no-deps -w dist .
-
-    - name: upload wheels
-      uses: actions/upload-artifact@v2
-      with:
-        name: frequenz-sdk-python-wheels
-        path: dist/*.whl
+      - name: Download dist files
+        uses: actions/download-artifact@v3
+        with:
+          name: frequenz-sdk-python-dist
+          path: dist
+
+      - name: Download RELEASE_NOTES.md
+        run: |
+          set -ux
+          gh api \
+              -X GET \
+              -f ref=$REF \
+              -H "Accept: application/vnd.github.raw" \
+              "/repos/$REPOSITORY/contents/RELEASE_NOTES.md" \
+            > RELEASE_NOTES.md
+        env:
+          REF: ${{ github.ref }}
+          REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub release
+        run: |
+          set -ux
+          extra_opts=
+          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 \
+            $REF_NAME \
+            dist/*
+        env:
+          REF_NAME: ${{ github.ref_name }}
+          REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-to-pypi:
+    needs: ["create-github-release"]
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Download dist files
+        uses: actions/download-artifact@v3
+        with:
+          name: frequenz-sdk-python-dist
+          path: dist
+
+      - name: Publish the Python distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip_existing: true

CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to `frequenz-sdk`
+
+## Build
+
+You can use `build` to simply build the source and binary distribution:
+
+```sh
+python -m pip install build
+python -m build
+```
+
+## Local development
+
+You can use editable installs to develop the project locally (it will install
+all the dependencies too):
+
+```sh
+python -m pip install -e .
+```
+
+You can also use `nox` to run the tests and other checks:
+
+```sh
+python -m pip install nox
+nox
+```
+
+You can also use `nox -R` to reuse the current testing environment to speed up
+test at the expense of a higher chance to end up with a dirty test environment.
+
+### Running tests individually
+
+For a better development test cycle you can install the runtime and test
+dependencies and run `pytest` manually.
+
+```sh
+python -m pip install .
+python -m pip install pytest pytest-asyncio
+
+# And for example
+pytest tests/test_sdk.py
+```
+
+## Releasing
+
+These are the steps to create a new release:
+
+1. Get the latest head you want to create a release from.
+
+2. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and
+   clean from template comments (`<!-- ... ->`) and empty sections. Submit
+   a pull request if an update is needed, wait until it is merged, and update
+   the latest head you want to create a release from to get the new merged pull
+   request.
+
+3. Create a new signed tag using the release notes and
+   a [semver](https://semver.org/) compatible version number with a `v` prefix,
+   for example:
+
+   ```sh
+   git tag -s -F RELEASE_NOTES.md v0.0.1
+   ```
+
+4. Push the new tag.
+
+5. A GitHub action will test the tag and if all goes well it will create
+   a [GitHub
+   Release](https://github.com/frequenz-floss/frequenz-sdk-python/releases),
+   create a new
+   [announcement](https://github.com/frequenz-floss/frequenz-sdk-python/discussions/categories/announcements)
+   about the release, and upload a new package to
+   [PyPI](https://pypi.org/project/frequenz-sdk/) automatically.
+
+6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
+
+   ```sh
+   cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
+   ```
+
+   Commit the new release notes and create a PR (this step should be automated
+   eventually too).
+
+7. Celebrate!

MANIFEST.in

@@ -0,0 +1,9 @@
+exclude .darglint
+exclude .gitignore
+exclude CODEOWNERS
+exclude minimum-requirements-ci.txt
+exclude noxfile.py
+recursive-exclude .github *
+recursive-exclude benchmarks *
+recursive-exclude examples *
+recursive-exclude tests *

README.md

@@ -2,44 +2,13 @@
 
 A development kit to interact with the Frequenz development platform.
 
-## Testing locally
-
-### Prerequisites
-
-#### Python version
+## Supported Python versions
 
 * For x86_64 Python 3.8 - 3.10 are supported (tested).
 * For arm64 only Python 3.8 is supported (due to some dependencies that only support 3.8).
 
-#### Development setup
-
-You need to install the following development dependencies to be able to get
-and build all dependencies:
-
-```sh
-python -m pip install grpcio-tools mypy-protobuf nox wheel
-```
-
-### Running the whole test suite
-
-Run the following command to run tests:
-
-```sh
-nox
-```
-
-You can also use `nox -R` to reuse the current testing environment to speed up
-test at the expense of a higher chance to end up with a dirty test environment.
-
-### Running tests individually
-
-For a better development test cycle you can install the runtime and test
-dependencies and run `pytest` manually.
-
-```sh
-python -m pip install .
-python -m pip install pytest pytest-asyncio
+## Contributing
 
-# And for example
-pytest tests/test_sdk.py
-```
+If you want to know how to build this project and contribute to it, please
+check out the [Contributing
+Guide](https://github.com/frequenz-floss/frequenz-sdk-python/CONTRIBUTING.md).

RELEASE_NOTES.md

@@ -0,0 +1,25 @@
+# `frequenz-sdk` Release Notes
+
+## Summary
+
+This is the first public open source release based on the internal SDK version v0.10.0. There are no breaking changes in this release, only changes to the project structure, metadata, and automation. Packages are also now uploaded to PyPI as [`frequenz-sdk`](https://pypi.org/project/frequenz-sdk/), so this project now can be installed normally via `pip`:
+
+```sh
+python -m pip install frequenz-sdk
+```
+
+The GitHub issues were also improved, adding templates for [reporting issues](https://github.com/frequenz-floss/frequenz-sdk-python/issues/new?assignees=&labels=priority%3A%E2%9D%93%2C+type%3Abug&template=bug.yml) and [requesting features](https://github.com/frequenz-floss/frequenz-sdk-python/issues/new?assignees=&labels=part%3A%E2%9D%93%2C+priority%3A%E2%9D%93%2C+type%3Aenhancement&template=feature.yml). Users are also pointed to the [Discussion forums](https://github.com/frequenz-floss/frequenz-sdk-python/issues/new/choose) when trying to open an issue if they have questions instead. Also many labels are assigned automatically on issue and pull request creation.
+
+## Upgrading
+
+Even if there are no breaking changes, you might see this error in your local
+environment when upgrading:
+
+    ERROR: Project file:///home/luca/devel/frequenz-sdk-python has
+    a 'pyproject.toml' and its build backend is missing the 'build_editable'
+    hook. Since it does not have a 'setup.py' nor a 'setup.cfg', it cannot be
+    installed in editable mode. Consider using a build backend that supports PEP
+    660.
+
+If so, you should probably update the dependencies in you virtual environment
+(for example `python -m pip install -U -e .`)