Skip to content

Latest commit

 

History

History
152 lines (94 loc) · 4.48 KB

DEVELOP.rst

File metadata and controls

152 lines (94 loc) · 4.48 KB
Raw

CrateDB Python developer guide

Setup

To start things off, bootstrap the sandbox environment:

git clone https://github.com/crate/crate-python
cd crate-python
source bootstrap.sh

This command should automatically install all prerequisites for the development sandbox and drop you into the virtualenv, ready for invoking further commands.

Running tests

All tests will be invoked using the Python interpreter that was used when creating the Python virtualenv. The test runner is zope.testrunner.

Some examples are outlined below. In order to learn about more details, see, for example, useful command-line options for zope-testrunner.

Run all tests:

./bin/test -vvvv

Run specific tests:

./bin/test -vvvv -t SqlAlchemyCompilerTest
./bin/test -vvvv -t test_score
./bin/test -vvvv -t sqlalchemy

Ignore specific test directories:

./bin/test -vvvv --ignore_dir=testing

The LayerTest test cases have quite some overhead. Omitting them will save a few cycles (~70 seconds runtime):

./bin/test -t '!LayerTest'

Invoke all tests without integration tests (~15 seconds runtime):

./bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest'

Yet ~130 test cases, but only ~5 seconds runtime:

./bin/test --layer '!crate.testing.layer.crate' --test '!LayerTest' \
    -t '!test_client_threaded' -t '!test_no_retry_on_read_timeout' \
    -t '!test_wait_for_http' -t '!test_table_clustered_by'

To inspect the whole list of test cases, run:

./bin/test --list-tests

You can run the tests against multiple Python interpreters with tox:

tox

To do this, you will need the respective Python interpreter versions available on your $PATH.

To run against a single interpreter, you can also invoke:

tox -e py37

Note: Before running the tests, make sure to stop all CrateDB instances which are listening on the default CrateDB transport port to avoid side effects with the test layer.

Renew certificates

For conducting TLS connectivity tests, there are a few X.509 certificates at src/crate/client/pki/*.pem. In order to renew them, follow the instructions within the README file in this folder.

Preparing a release

To create a new release, you must:

  • Backport your bug fixes to the latest stable branch x.y (e.g. 0.19)
  • For new features, create a new stable branch x.(y+1) (e.g. 0.20)

In the release branch:

  • Update __version__ in src/crate/client/__init__.py
  • Add a section for the new version in the CHANGES.txt file
  • Commit your changes with a message like "prepare release x.y.z"
  • Push to origin/<release_branch>
  • Create a tag by running ./devtools/create_tag.sh. This will trigger a Github action which releases the new version to PyPi.

On master:

  • Update the release notes to reflect the release

Next:

  • Archive docs for old releases (see section below)

Archiving docs versions

Check the versions hosted on ReadTheDocs.

We should only be hosting the docs for latest, stable, and the most recent patch versions for the last two minor releases.

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

Writing documentation

The docs live under the docs directory.

The docs are written written with ReStructuredText and processed with Sphinx.

Build the docs by running:

./bin/sphinx

The output can then be found in the out/html directory.

The docs are automatically built from Git by Read the Docs and there is nothing special you need to do to get the live docs to update.