Skip to content

Commit 9cf6e06

Browse files
amunraamunra
committed
docs: Updated docs to release the client lib
1 parent 16d6741 commit 9cf6e06

File tree

2 files changed

+204
-33
lines changed

2 files changed

+204
-33
lines changed

‎DEV_NOTES.rst‎

Lines changed: 2 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -125,41 +125,10 @@ The `-e` flag links to the current directory rather than copying.
125125
$ python3 sdist
126126
127127
128-
Uploading to PyPI
128+
Cutting a release
129129
-----------------
130130

131-
Update the change log file that describes the latest changes in aggregate.
132-
133-
.. code-block:: bash
134-
135-
vim CHANGELOG.rst
136-
137-
138-
Create a tag, update versions etc using ``bump2version``.
139-
140-
For more command line options, see: https://pypi.org/project/bump2version/
141-
142-
Note that here ``patch`` would bump from (for example) ``0.1.0`` to
143-
``0.1.1``. ``minor`` would bump from ``0.1.0`` to ``0.2.0`` and ``major``
144-
would bump from ``0.1.0`` to ``1.0.0``.
145-
146-
.. code-block:: bash
147-
148-
bump2version --config-file .bumpversion.cfg patch
149-
150-
151-
Now make sure you push the tag or it will not show up in GitHub:
152-
153-
.. code-block:: bash
154-
155-
git push --tags
156-
157-
158-
Once you've triple-checked everything is in ``dist/``, you can upload to PyPI.
159-
160-
.. code-block:: bash
161-
162-
python3 -m twine upload dist/*
131+
This is a semi-automated process, covered in ``RELEASING.rst``.
163132

164133

165134
Debugging with on Linux

‎RELEASING.rst‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
Cutting a new release
2+
=====================
3+
4+
Overview
5+
--------
6+
7+
We will collate the generated binaries from CI, together with a final
8+
binary we need to build manually from for MacOS ARM within a MacOS VM.
9+
10+
We cut from a VM to use as old of a MacOS version as possible to ensure
11+
backwards compatibility with older MacOS versions.
12+
13+
From the VM we will also bundle a source distribution and perform the final
14+
upload to PyPI.
15+
16+
Bumping Version and updating Changelog
17+
--------------------------------------
18+
19+
Create a new PR with the new changes in ``src/CHANGELOG.md``.
20+
21+
Make a commit and push the changes to a new branch.
22+
23+
You also want to bump the version.
24+
25+
This process is automated by the following command:
26+
27+
.. code-block:: bash
28+
29+
bump2version --config-file .bumpversion.cfg --no-tag patch
30+
31+
Here use:
32+
33+
* ``patch`` to bump the version to the next patch version, e.g. 1.0.0 -> 1.0.1
34+
35+
* ``minor`` to bump the version to the next minor version, e.g. 1.0.0 -> 1.1.0
36+
37+
* ``major`` to bump the version to the next major version, e.g. 1.0.0 -> 2.0.0
38+
39+
Now merge the PR with the title "Bump version: V.V.V → W.W.W".
40+
41+
Note that CI will run all the ``cibuildwheel`` jobs which will in turn
42+
generate the binaries for all the platforms, except for MacOS ARM.
43+
44+
Preparing the MacOS VM
45+
----------------------
46+
47+
Skip if you already have the MacOS VM set up in UTM.
48+
49+
.. warn::
50+
51+
Releasing from an up to date MacOS install will not work as the binaries
52+
may be incompatible with older MacOS versions.
53+
54+
From a MacOS ARM computer install UTM.
55+
56+
* Download from https://mac.getutm.app/
57+
* Install MacOS X 12.4 (Monterey). See https://docs.getutm.app/guest-support/macos/
58+
* Install Xcode from the App Store
59+
* Install Rust from https://rustup.rs/
60+
* Install Firefox
61+
* Install *all* OFFICIAL Python eleases from Python 3.8 onwards.
62+
* https://www.python.org/downloads/macos/
63+
* Do NOT use Homebrew to install Python.
64+
65+
* Optionally install VS Code
66+
67+
Now clone the repository. The rest of the steps will assume this is done as so::
68+
69+
cd ~
70+
mkdir -p questdb
71+
cd questdb
72+
git clone https://github.com/questdb/py-questdb-client.git
73+
cd py-questdb-client
74+
git submodule update --init --recursive
75+
76+
Updating the MacOS VM
77+
---------------------
78+
79+
Do this before every release.
80+
81+
Inside the VM, open a terminal (or use the terminal Window in VSCode) and run the following commands::
82+
83+
cd ~/questdb/py-questdb-client
84+
git checkout main
85+
git pull
86+
git submodule update --init --recursive
87+
88+
rustup update stable
89+
90+
/Library/Frameworks/Python.framework/Versions/3.8/bin/python3 \
91+
-m pip install --U pip
92+
/Library/Frameworks/Python.framework/Versions/3.8/bin/python3 \
93+
-m pip install --U setuptools wheel twine Cython cibuildwheel pandas numpy pyarrow
94+
95+
Smoke-testing the build
96+
-----------------------
97+
98+
From ``~/questdb/py-questdb-client`` run the following commands::
99+
100+
./proj clean
101+
./proj build
102+
./proj test
103+
104+
105+
Building the MacOS ARM binaries
106+
-------------------------------
107+
108+
Clean and build the final binaries for each Python version::
109+
110+
./proj clean
111+
./proj cibuildwheel
112+
113+
This should have created new binaries in the ``dist/`` directory.
114+
115+
Prepare the source distribution
116+
-------------------------------
117+
118+
The source code distribution is for any other platforms that we don't have
119+
binaries for. I don't think it's _actually_ used by anyone, but it might get
120+
used by IDEs.
121+
122+
.. code-block:: bash
123+
124+
python3 setup.py sdist
125+
126+
Download the other binaries from CI
127+
-----------------------------------
128+
129+
From the MacOS VM, From a terminal, run::
130+
131+
cd ~/Downloads
132+
rm drop.zip
133+
rm -rf drop
134+
135+
Launch Firefox and log into GitHub and open the last (closed and merged) PR.
136+
137+
Click on the "Checks" tab and open up the last "questdb.py-questdb-client (1)"
138+
check. There will be a link to the Azure DevOps page.
139+
140+
The following link might also work: https://dev.azure.com/questdb/questdb/_build?definitionId=21&_a=summary
141+
142+
If you open up the last run, you'll find a link called "1 published".
143+
This will redirect you to the "Publushed artifacts" page.
144+
145+
There will be a "drop" directory.
146+
* Don't open it.
147+
* Instead use click on the three vertical dots on the right-hand
148+
side and select download artifacts.
149+
150+
This will download a file called "drop.zip".
151+
152+
double-check it in Finder: It will extract to a directory called "drop".
153+
154+
Now from the terminal, run::
155+
156+
cd ~/questdb/py-questdb-client
157+
cp -vr ~/Downloads/drop/* dist/
158+
159+
160+
Tagging the release
161+
-------------------
162+
163+
In GitHub with a web browser create a new release with the tag "vX.Y.Z"
164+
(where X.Y.Z is the new version number).
165+
166+
The release notes should be copied from the ``CHANGELOG.rst`` file,
167+
but reformatted as Markdown.
168+
169+
170+
Uploading to PyPI
171+
-----------------
172+
173+
Now the MacOS VM has all the binaries and the source distribution, ready to be
174+
uploaded to PyPI.
175+
176+
This is a good time to double-check you can log into PyPI and have set up an
177+
API token. If you don't have one (or lost it), you can create a new one here:
178+
https://pypi.org/manage/account/ (scroll down to "API tokens").
179+
180+
Once you've triple-checked everything is in ``dist/``, you can upload to PyPI.
181+
182+
.. code-block:: bash
183+
184+
python3 -m twine upload dist/*
185+
186+
This will prompt you for your PyPI username and token.
187+
188+
Once the upload is complete, you can check the PyPI page to see if the new
189+
release is there: https://pypi.org/project/questdb/
190+
191+
192+
Updating the docs
193+
-----------------
194+
195+
Log into ReadTheDocs and trigger a new build for the project.
196+
197+
https://readthedocs.org/dashboard/py-questdb-client/users/
198+
199+
Watch it to ensure there are no errors.
200+
201+
Once the build is complete, COMMAND-SHIFT-R to refresh the page (without cache)
202+
and check the new version is there.

0 commit comments

Comments
 (0)