Contributing to Frequenz Python SDK¤
You can use
build to simply build the source and binary distribution:
You can use editable installs to develop the project locally (it will install all the dependencies too):
Or you can install all development dependencies (
etc.) in one go too:
If you don't want to install all the dependencies, you can also use
run the tests and other checks creating its own virtual environments:
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 / checks individually¤
For a better development test cycle you can install the runtime and test
dependencies and run
Or you can use
The same appliest to
mypy for example:
Building the documentation¤
To build the documentation, first install the dependencies (if you didn't
Then you can build the documentation (it will be written in the
Or you can just serve the documentation without building it using:
Your site will be updated live when you change your files (provided that
pip install -e ., beware of a common pitfall of using
-e, in that case the API reference won't change unless you do a new
To build multi-version documentation, we use mike. If you want to see how the multi-version sites looks like locally, you can use:
mike works in mysterious ways. Some basic information:
mike deploywill do a
mike buildand write the results to your local
my-versionis an arbitrary name for the local version you want to preview.
mike set-defaultis needed so when you serve the documentation, it goes to your newly produced documentation by default.
mike servewill serve the contents of your local
gh-pagesbranch. Be aware that, unlike
mkdocs serve, changes to the sources won't be shown live, as the
mike deploystep is needed to refresh them.
Be careful not to use
mike deploy, otherwise it will push your
gh-pages branch to the
That said, if you want to test the actual website in your fork, you can
mike deploy --push --remote your-fork-remote, and then access the
GitHub pages produced for your fork.
These are the steps to create a new release:
Get the latest head you want to create a release from.
RELEASE_NOTES.mdfile if it is not complete, up to date, and remove 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.
Create a new signed tag using the release notes and a semver compatible version number with a
vprefix, for example:
Push the new tag.
Once this is done, reset the
RELEASE_NOTES.mdwith the template:
Commit the new release notes and create a PR (this step should be automated eventually too).