Skip to content

Commit b5dae8a

Browse files
Lorak-mmkLorak-mmk
committed
README-dev: Update the document
Updated section about releasing, testing and documentation to match current tooling and procedures. Removed some sections that are no longer relevant.
1 parent d7169b4 commit b5dae8a

File tree

1 file changed

+24
-128
lines changed

1 file changed

+24
-128
lines changed

‎README-dev.rst

Lines changed: 24 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,16 @@
11
Releasing
22
=========
33
* Run the tests and ensure they all pass
4-
* Update CHANGELOG.rst
5-
* Check for any missing entries
6-
* Add today's date to the release section
74
* Update the version in ``cassandra/__init__.py``
8-
* For beta releases, use a version like ``(2, 1, '0b1')``
9-
* For release candidates, use a version like ``(2, 1, '0rc1')``
10-
* When in doubt, follow PEP 440 versioning
11-
* Add the new version in ``docs.yaml``
12-
* Commit the changelog and version changes, e.g. ``git commit -m'version 1.0.0'``
13-
* Tag the release. For example: ``git tag -a 1.0.0 -m 'version 1.0.0'``
14-
* Push the tag and new ``master``: ``git push origin 1.0.0 ; git push origin master``
15-
* Update the `python-driver` submodule of `python-driver-wheels`,
16-
commit then push. This will trigger TravisCI and the wheels building.
17-
* For a GA release, upload the package to pypi::
18-
19-
# Clean the working directory
20-
python setup.py clean
21-
rm dist/*
22-
23-
# Build the source distribution
24-
python setup.py sdist
25-
26-
# Download all wheels from the jfrog repository and copy them in
27-
# the dist/ directory
28-
cp /path/to/wheels/*.whl dist/
29-
30-
# Upload all files
31-
twine upload dist/*
32-
33-
* On pypi, make the latest GA the only visible version
34-
* Update the docs (see below)
35-
* Append a 'postN' string to the version tuple in ``cassandra/__init__.py``
36-
so that it looks like ``(x, y, z, 'postN')``
37-
38-
* After a beta or rc release, this should look like ``(2, 1, '0b1', 'post0')``
39-
40-
* After the release has been tagged, add a section to docs.yaml with the new tag ref::
41-
42-
versions:
43-
- name: <version name>
44-
ref: <release tag>
45-
46-
* Commit and push
47-
* Update 'cassandra-test' branch to reflect new release
48-
49-
* this is typically a matter of merging or rebasing onto master
50-
* test and push updated branch to origin
51-
52-
* Update the JIRA versions: https://datastax-oss.atlassian.net/plugins/servlet/project-config/PYTHON/versions
53-
54-
* add release dates and set version as "released"
55-
56-
* Make an announcement on the mailing list
5+
* Add the new version in ``docs/conf.py`` (variables: ``TAGS``, ``LATEST_VERSION``, ``DEPRECATED_VERSIONS``).
6+
* For patch version releases (like ``3.26.8-scylla -> 3.26.9-scylla``) replace the old version with new one in ``TAGS`` and update ``LATEST_VERSION``.
7+
* For minor version releases (like ``3.26.9-scylla -> 3.27.0-scylla``) add new version to ``TAGS``, update ``LATEST_VERSION`` and add previous minor version to ``DEPRECATED_VERSIONS``.
8+
* Commit the version changes, e.g. ``git commit -m 'Release 3.26.9'``
9+
* Tag the release. For example: ``git tag -a 3.26.9-scylla -m 'Release 3.26.9'``
10+
* Push the tag and new ``master`` SIMULTANEOUSLY: ``git push --atomic origin master v6.0.21-scylla``
11+
* Now new version and its docs should be automatically published. Check `PyPI <https://pypi.org/project/scylla-driver/#history>`_ and `docs <https://python-driver.docs.scylladb.com/stable/>`_ to make sure its there.
12+
* If you didn't push branch and tag simultaneously (or doc publishing failed for other reason) then restart the relevant job from GitHub Actions UI.
13+
* Publish a GitHub Release and a post on community forum.
5714

5815
Building the Docs
5916
=================
@@ -62,7 +19,10 @@ To build and preview the documentation for the ScyllaDB Python driver locally, y
6219
This is necessary for autogenerating the reference documentation of the driver.
6320
You can find detailed instructions on how to install the driver in the `Installation guide <https://python-driver.docs.scylladb.com/stable/installation.html#manual-installation>`_.
6421

65-
After installing the driver, you can build and preview the documentation by following the steps outlined in the `Quickstart guide <https://sphinx-theme.scylladb.com/stable/getting-started/quickstart.html>`_.
22+
After installing the driver, you can build the documentation:
23+
- Make sure you have Python version compatible with docs. You can see supported version in ``docs/pyproject.toml`` - look for ``python`` in ``tool.poetry.dependencies`` section.
24+
- Install poetry: ``pip install poetry``
25+
- To preview docs in your browser: ``make -C docs preview``
6626

6727
Tests
6828
=====
@@ -81,26 +41,22 @@ You can run a specific test method like so::
8141

8242
Running Integration Tests
8343
-------------------------
84-
In order to run integration tests, you must specify a version to run using the ``CASSANDRA_VERSION`` or ``DSE_VERSION`` environment variable::
85-
86-
CASSANDRA_VERSION=2.0.9 nosetests -w tests/integration/standard
87-
88-
Or you can specify a cassandra directory (to test unreleased versions)::
44+
In order to run integration tests, you must specify a version to run using either of:
45+
* ``SCYLLA_VERSION`` e.g. ``release:5.1``
46+
* ``CASSANDRA_VERSION``
47+
environment variable::
8948

90-
CASSANDRA_DIR=/home/thobbs/cassandra nosetests -w tests/integration/standard/
91-
92-
Specifying the usage of an already running Cassandra cluster
93-
------------------------------------------------------------
94-
The test will start the appropriate Cassandra clusters when necessary but if you don't want this to happen because a Cassandra cluster is already running the flag ``USE_CASS_EXTERNAL`` can be used, for example::
95-
96-
USE_CASS_EXTERNAL=1 CASSANDRA_VERSION=2.0.9 nosetests -w tests/integration/standard
49+
SCYLLA_VERSION="release:5.1" python -m pytest tests/integration/standard tests/integration/cqlengine/
9750

9851
Specify a Protocol Version for Tests
9952
------------------------------------
100-
The protocol version defaults to 1 for cassandra 1.2 and 2 otherwise. You can explicitly set
101-
it with the ``PROTOCOL_VERSION`` environment variable::
53+
The protocol version defaults to:
54+
- 4 for Scylla >= 3.0 and Scylla Enterprise > 2019.
55+
- 3 for older versions of Scylla
56+
- 5 for Cassandra >= 4.0, 4 for Cassandra >= 2.2, 3 for Cassandra >= 2.1, 2 for Cassandra >= 2.0
57+
You can overwrite it with the ``PROTOCOL_VERSION`` environment variable::
10258

103-
PROTOCOL_VERSION=3 nosetests -w tests/integration/standard
59+
PROTOCOL_VERSION=3 SCYLLA_VERSION="release:5.1" python -m pytest tests/integration/standard tests/integration/cqlengine/
10460

10561
Seeing Test Logs in Real Time
10662
-----------------------------
@@ -112,14 +68,6 @@ Use tee to capture logs and see them on your terminal::
11268

11369
python -m pytest -s tests/unit/ 2>&1 | tee test.log
11470

115-
Testing Multiple Python Versions
116-
--------------------------------
117-
If you want to test all of python 2.7, 3.5, 3.6, 3.7, and pypy, use tox (this is what
118-
TravisCI runs)::
119-
120-
tox
121-
122-
By default, tox only runs the unit tests.
12371

12472
Running the Benchmarks
12573
======================
@@ -135,55 +83,3 @@ There are a few options. Use ``--help`` to see them all::
13583

13684
python benchmarks/future_batches.py --help
13785

138-
Packaging for Cassandra
139-
=======================
140-
A source distribution is included in Cassandra, which uses the driver internally for ``cqlsh``.
141-
To package a released version, checkout the tag and build a source zip archive::
142-
143-
python setup.py sdist --formats=zip
144-
145-
If packaging a pre-release (untagged) version, it is useful to include a commit hash in the archive
146-
name to specify the built version::
147-
148-
python setup.py egg_info -b-`git rev-parse --short HEAD` sdist --formats=zip
149-
150-
The file (``dist/scylla-driver-<version spec>.zip``) is packaged with Cassandra in ``cassandra/lib/scylla-driver-internal-only*zip``.
151-
152-
Releasing an EAP
153-
================
154-
155-
An EAP release is only uploaded on a private server and it is not published on pypi.
156-
157-
* Clean the environment::
158-
159-
python setup.py clean
160-
161-
* Package the source distribution::
162-
163-
python setup.py sdist
164-
165-
* Test the source distribution::
166-
167-
pip install dist/scylla-driver-<version>.tar.gz
168-
169-
* Upload the package on the EAP download server.
170-
* Build the documentation::
171-
172-
python setup.py doc
173-
174-
* Upload the docs on the EAP download server.
175-
176-
Adding a New Python Runtime Support
177-
===================================
178-
179-
* Add the new python version to our jenkins image:
180-
https://github.com/riptano/openstack-jenkins-drivers/
181-
182-
* Add the new python version in job-creator:
183-
https://github.com/riptano/job-creator/
184-
185-
* Run the tests and ensure they all pass
186-
* also test all event loops
187-
188-
* Update the wheels building repo to support that version:
189-
https://github.com/riptano/python-dse-driver-wheels

0 commit comments

Comments
 (0)