First, check to see if there's an existing issue/pull request for the bug/feature. All issues are at https://github.com/vortechsa/python-sdk/issues and pull reqs are at https://github.com/vortechsa/python-sdk/pulls.
If there isn't an existing issue there, please file an issue. The ideal report includes:
- A description of the problem/suggestion.
- How to recreate the bug (including the version on your python interpreter).
- If possible, create a pull request with a (failing) test case demonstrating what's wrong. This makes the process for fixing bugs quicker & gets issues resolved sooner.
First, clone the repo, then cd
into the repo.
$ git clone git@github.com:vortechsa/python-sdk.git
$ cd python-sdk
create a new virtual environment
$ python3.7 -m venv venv
activate your environment
$ . venv/bin/activate
install the required dependencies
$ pip install -e '.[tests]'
To run the live tests, you'll need to have the VORTEXA_API_KEY
environment variable set - export VORTEXA_API_KEY=xyz
run tests
$ python setup.py test
If you're just looking to run tests in a single module (test_vessels
in this case), you can do like this:
$ pytest -v tests/endpoints/test_vessels.py
Run all the 'try-me-out' notebooks, and then clear the cell outputs so the data isn't publicly visible.
jupyter nbconvert --to notebook --inplace --execute docs/examples/try_me_out/*.ipynb
jupyter nbconvert --to notebook --inplace --clear-output docs/examples/try_me_out/*.ipynb
Serve documentation locally
$ ./docs/scripts/serve_docs.sh
…and view the docs at http://localhost:8000 in your web browser.
Install the git pre-commit-hooks
$ pre-commit install
🎉 Now you're ready to create a new branch, add a feature or fix a bug, then send us a pull request! 🎉
New versions of the SDK are automatically released to pypi when your branch PR is merged into the master branch.
In the branch you're working on, you'll need to change the version.py
file to the new version that you're looking to deploy.
The python-sdk follow strict semver, so you'll need to increment the MAJOR nunber if and only if you're introducing
a breaking change, the MINOR number if you're addind a new feature, or PATCH number if you've introduced a bug fix.
Once your branch is merged to master, CircleCI will do a few things:
- Deploy the new package to pypi https://pypi.org/project/vortexasdk/, using the version in
version.py
. - Update the github pages documentation at https://vortechsa.github.io/python-sdk/
- Create a git tag, usign the version in
version.py
A good pull request:
- Is clear.
- Follows the existing style of the code base (PEP-8).
- Has comments included as needed.
- A test case that demonstrates the previous flaw that now passes with the included patch, or demonstrates the newly added feature.
- If it adds/changes a public API, it must also include documentation for those changes.
Tips:
- If you're adding a new endpoint, adapt and use
./docs/generate_stubs.sh
to generate sample json data used for tests.
Please include the version of the SDK and any other packages used to generate the Jupyter Notebook at the start of the notebook. This helps others to reproduce your results in the future.
We adopt the Conventional Commits convention to format commit messages.
We're using Pydocmd to automatically generate docs.
Documentation should follow the Google Documentation Style Guide
Discussions about the VortexaSDK take place on this repository's https://github.com/vortechsa/python-sdk/issues and https://github.com/vortechsa/python-sdk/pulls sections. Anybody is welcome to join these conversations.
Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation.
Please see https://github.com/vortechsa/python-sdk/blob/master/CODE_OF_CONDUCT.md for the code of conduct.