1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
:orphan:
How to make a psycopg release
=============================
- Check if there is a new version or libpq_ or OpenSSL_; in such case
update ``LIBPQ_VERSION`` and/or ``OPENSSL_VERSION`` in
``.github/workflows/packages-bin.yml``.
.. _libpq: https://www.postgresql.org/ftp/source/
.. _OpenSSL: https://www.openssl.org/source/
- Check if there is a new `cibuildwheel release`__; if so, upgrade it in
``.github/workflows/packages-bin.yml``.
.. __: https://github.com/pypa/cibuildwheel/releases
- Use ``tools/bump_version.py`` to upgrade package version numbers.
- Push to GitHub to run `the tests workflow`__.
.. __: https://github.com/psycopg/psycopg/actions/workflows/tests.yml
- Build the packages by triggering manually the ones requested among:
- `Source packages`__
- `Binary packages`__
- `Pool packages`__
.. __: https://github.com/psycopg/psycopg/actions/workflows/packages-src.yml
.. __: https://github.com/psycopg/psycopg/actions/workflows/packages-bin.yml
.. __: https://github.com/psycopg/psycopg/actions/workflows/packages-pool.yml
- Delete the ``wheelhouse`` directory if there is one.
- If all packages were built ok, push the new tag created by ``bump_version.py``::
git push --tags
- Download the ``artifacts.zip`` package from the last Packages workflow run.
- Unpack the packages in the wheelhouse dir::
mkdir -p wheelhouse
cd wheelhouse
unzip ~/Downloads/artifact.zip
- If the package is a testing one, upload it on TestPyPI with::
$ twine upload -r testpypi *
- If the package is stable, omit ``-r testpypi``::
$ twine upload *
- Run ``tools/bump_version.py -l dev`` to bump to the next dev version.
When a new PostgreSQL major version is released
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Add the new version to ``tools/update_errors.py`` and run the script to add
new error classes.
- If the script above found any change, document the version added at the
bottom of ``docs/api/errors.rst``.
- Run the script ``tools/update_oids.py`` to add new oids. Use ``-h`` to get
an example docker command line to run a server locally.
- Check if there are new enum values to include in:
- ``psycopg_c/psycopg_c/pq/libpq.pxd``;
- ``psycopg/psycopg/pq/_enums.py``.
- Include the new version in GitHub Actions test and package grids.
- Bump ``PG_VERSION`` in the ``macos`` job of
- ``.github/workflows/packages-bin.yml``.
- ``.github/workflows/tests.yml``.
- Update the documented versions in:
- ``docs/basic/install.rst``;
- ``content/features/contents.lr`` in the psycopg-website repository.
Adding new libpq wrapper methods
--------------------------------
The ``psycopg.pq`` module is a thin wrapper around the libpq, only doing the
minimal work to make the library somewhat Pythonic (e.g. converting types and
raising exceptions instead of returning error values).
When new functionalities are added to the libpq we often want to expose them
to Python (either to allow Python users to use them directly or to build new
features on top of them). The procedure touches several files, in order to
add function wrappers to both the Python and the C implementation of the
libpq, to the objects interfaces and every object implementing them, and
eventually to bubble up to some Python object.
It is polite to add new top-level objects interfaces (such as
``connection.info`` or ``Capabilities`` only on minor releases (3.x), but if
we need to add a libpq function wrapper to solve an issue we can do it in a
bugfix release, without documenting it (e.g. ``PQconnectionUsedGSSAPI`` was
added in 3.2.10 but only advertised in 3.3).
You can use `PR 1140`__ as a reference for the work to do (code, tests,
documentation). In this MR, the changes in the first commit are suitable to
introduce a new function in a bugfix release, the second commit changes make
the new functionality public.
.. __: https://github.com/psycopg/psycopg/pull/1140/
When a new Python major version is released
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Add the new version to the relevant test matrices in
``.github/workflows/tests.yml`` and ``.github/workflows/packages-bin.yml``.
- Update ``docs/basic/install.rst`` with the correct range of supported Python
versions.
- Add the ``Programming Language :: Python :: 3.<X>`` classifier to
``psycopg/pyproject.toml``, ``psycopg_c/pyproject.toml``, and
``psycopg_pool/pyproject.toml``.
When dropping end-of-life Python versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Update project metadata, ``requires-python`` and (maybe) package dependencies
in ``pyproject.toml`` files of the corresponding ``psycopg`` directories.
- Update GitHub Actions workflow files in the ``.github/workflows/`` directory,
e.g., ``tests.yml``, ``.3rd-party-tests.yml``, ``packages-bin.yml``.
- Bump versions in the ``tests/constraints.txt`` file if it is necessary.
- bump ``build-system.requires`` in ``*/pyproject.toml``. Install the packages
with ``pip install ./psycopg*/`` and check eventual warnings.
- You may grep throughout the project for occurrences of a version to be dropped.
However, favouring smaller pull requests is convenient and easy to review.
An example for grepping `end-of-life <https://endoflife.date/python>` Python 3.8::
git grep -E -e '\b3\.8\b' -e '\b(cp)?38\b' -e '\b3, 8\b'
git grep -E -e '\b3\.9\b' -e '\b(cp)?39\b' -e '\b3, 9\b'
- Consider using pyupgrade_ with ``--py3NN-plus`` in order to refresh syntax
to Python 3.NN (the new minimum supported version).
.. _pyupgrade: https://pypi.org/project/pyupgrade/
Examples:
- `PR #977 <https://github.com/psycopg/psycopg/pull/977>`_
|
