Skip to content

Latest commit

 

History

History
220 lines (139 loc) · 6.05 KB

DEVELOP.rst

File metadata and controls

220 lines (139 loc) · 6.05 KB
Raw

Developer Guide

Setup

Pip

Python >= 3.6 is required. Run croud within a virtual python environment:

python -m venv env
source env/bin/activate

Install the croud package:

pip install -e .
pip install -e ".[development]"

Run it:

croud -h

Git

Alternatively, you can clone this repository, install it into a virtualenv and add the executable to your PATH environment variable:

git clone git@github.com:crate/croud.git && cd croud/
python3.6 -m venv env
env/bin/pip install -e .
export PATH=$PATH:$(pwd)/env/bin/croud

Testing

Install the dependencies used for testing:

pip install -e ".[testing]"

Tests run with pytest inside a tox environment.

To run unit tests across the whole test suite with the supported python versions run:

tox

Alongside -- it's possible to pass pytest args e.g. to run only a fraction of tests with python3.6:

tox -e py36 -- -k test_rest

The test setup uses pytest-random-order to ensure better test separation. By default, the order will be random on the Python module level. That means, essentially, the order of *.py files will be randomized when running tests.

When running tests using tox or py.test, pytest-random-order will emit a seed value at the beginning which can be used to rerun tests with the specific order:

$ tox -e py37
...
py37 run-test-pre: PYTHONHASHSEED='2789788418'
py37 run-test: commands[0] | pytest
======================== test session starts =========================
platform linux -- Python 3.7.3, pytest-3.10.1, py-1.8.0, pluggy-0.12.0
Using --random-order-bucket=module
Using --random-order-seed=240261
...

One can rerun a random test setup by passing --random-order-seed=<seed> to py.test:

$ tox -e py37 -- --random-order-seed=240261

Debugging API calls

When developing, it's often useful to see what API calls Croud is making. To do that, simply set the LOG_API environment variable to true:

$ LOG_API=true croud clusters list
==> Debug: GET https://console.cratedb.cloud/api/v2/clusters/
+-----------+--------+-------------+-----------------+-------------+------------+----------+-----------+
| id        | name   |   num_nodes | crate_version   | project_id  | username   | fqdn     | channel   |
|-----------+--------+-------------+-----------------+-------------+------------+----------+-----------|
+-----------+--------+-------------+-----------------+-------------+------------+----------+-----------+

Code style checks and static analysis

This project uses pre-commit to ensure linting, code formatting, and type checking. Tools, such as black, flake8, isort, and mypy can be run as hooks upon committing and/or pushing code. When at least one of the hooks fails, committing or pushing changes is aborted and manual intervention is necessary.

Install pre-commit for your user and verify that the installation worked:

$ python -m pip install --user pre-commit

After the successful installation, install the hooks for this project:

$ pre-commit install -t pre-commit -t pre-push --install-hooks
pre-commit installed at .git/hooks/pre-commit
pre-commit installed at .git/hooks/pre-push

...

From now on, each time you run git commit or git push, hooks defined in the file .pre-commit-config.yaml will run on staged files.

Release

  1. Create a new branch named <prefix>/prepare-x.y.z.
  2. Update the __version__ in setup.py.
  3. Add new section to CHANGES.rst with the version and release date in the format x.y.z - yyyy/mm/dd.
  4. Create a PR against master or version branch (e.g. 0.1).

  5. After PR is merged, tag the release by running:

    ./dev/tools/create_tag.sh

Upload to PyPI

Pushing a tag to Github will trigger a Github workflow that builds and uploads the croud package to PyPI automatically.

Note

It is recommended to build a package locally and upload it to Test PyPI first which is intended for experimentation and testing.

Documentation

The documentation is written using Sphinx and ReStructuredText.

Working on the documentation

Python 3.7 is required.

Change into the docs directory:

$ cd docs

For help, run:

$ make

Crate Docs Build

Run `make <TARGET>`, where <TARGET> is one of:

  dev     Run a Sphinx development server that builds and lints the
          documentation as you edit the source files

  html    Build the static HTML output

  check   Build, test, and lint the documentation

  reset   Reset the build cache

You must install fswatch to use the dev target.

Continuous integration and deployment

CI is configured to run make check from the docs directory. Please do not merge pull requests until the tests pass.

Read the Docs automatically deploys the documentation whenever a configured branch is updated.

To make changes to the RTD configuration (e.g., to activate or deactivate a release version), please contact the @crate/tech-writing team.