First: if you're unsure or afraid of anything, just ask or submit the issue or pull request anyways. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate all contributions!
The DigitalOcean Python client is generated using AutoRest. The AutoRest tool generates client libraries for accessing RESTful web services. Input to AutoRest is a spec that describes the DigitalOcean REST API using the OpenAPI 3.0 Specification format. The spec can be found here. AutoRest allows customizations to be made on top of the generated code.
PyDo is a generated client. This section will walk you through generating the client locally. One might ask, when would one want to generate PyDo locally? Local generation is really helpful when making changes to the client configuration itself. It is good practice to re-generate the client to ensure the behavior is as expected.
- Python version: >= 3.9 (it's highly recommended to use a python version management tool)
- poetry: python packaging and dependency management
- AutoRest: The tool that generates the client libraries for accessing RESTful web services.
We chose not to tie this repository to tooling for managing python installations. This allows developers to use their preferred tooling.
We like these:
- pyenv: python version management
- pyenv-virtualenv: a pyenv plugin to enable pyenv to manage virtualenvs for development environment isolation
-
Clone this repository. Run:
git clone [email protected]:digitalocean/pydo.git cd pydo
-
(Optional) Ensure you have the right version of python installed using your preferred python version manager. This is what you'd run if you used
pyenv
:pyenv install 3.9.4
This can take a few minutes.
-
Install the package dependencies
poetry install
-
You can now activate your virtual environment
poetry shell
-
Remove the previous generated code.
make clean
-
Re-download the latest DO OpenAPI 3.0 Specification.
make download-spec
-
Generate the client
make generate
It is also good practice to run mock tests against the changes using the following make command:
make test-mocked
On top of generating our client, we've added a few customizations to create an optimal user experience. These customizations can by making changes to the _patch.py
file. To learn more about adding customizations, please follow Autorest's documentation for it here
The repo uses GitHub workflows to publish a draft release when a new tag is pushed. We use semver to determine the version number vor the tag.
-
Run
make changes
to review the merged PRs since last release and decide what kind of release you are doing (bugfix, feature or breaking).- Review the tags on each PR and make sure they are categorized appropriately.
-
Run
BUMP=(bugfix|feature|breaking) make bump_version
to update thepydo
version.
BUMP
also accepts(patch|minor|major)
Command example:
make BUMP=minor bump_version
-
Update the Pydo version in
pyproject.toml
andsrc/pydo/_version.py
. Create a separate PR with only these changes. -
Once the PR has been pushed and merged, tag the commit to trigger the release workflow: run
make tag
to tag the latest commit and push the tag to ORIGIN.Notes:
- To tag an earlier commit, run
COMMIT=${commit} make tag
. - To push the tag to a different remote, run
ORIGIN=${REMOTE} make tag
.
- To tag an earlier commit, run
-
Once the release process completes, review the draft release for correctness and publish the release.
Ensure the release has been markedLatest
.