Release process

Here are some guidelines on how to do a release of pyodbc to PyPi:

Prerequisites

1. You'll need an account on the Python Package Index (PyPi) website, with the privileges to upload files to the pyodbc project.

2. (Optional) an account on the Test Python Package Index (Test PyPi) website, with the privileges to upload files to the pyodbc project. Note, accounts on PyPi and Test PyPi are completely separate. You'll need two accounts.

3. The Python twine utility for uploading build files to PyPi. It's recommended to install this using pipx so it is universally available but doesn't pollute your system Python installation(s).

Process

1. Check the package version for the new release in setup.py (see the VERSION constant). If that value is not correct, change it and commit, then wait for the CI pipelines to complete (manually triggering them if necessary). The package version should be PEP-440 compliant, for example "5.2.0".

2. Choose the git commit that will be used for the release. This will almost always be the head of the master branch, but it can theoretically be any commit. Take a note of the commit number ("SHA").

   https://github.com/mkleehammer/pyodbc/commits/master

3. In your local pyodbc repository, create an annotated git tag for the chosen commit, as follows:

   git tag --annotate <package version> <commit SHA>

   For example: git tag --annotate "5.2.0" "715e1ddc266e1f8d4cbb741291011ee4a5664811"

   You will be prompted to enter a message for the tag. Give a short description of the release, a fuller description will be added to the Github release notes later.

   Push this tag to Github.

4. In your local pyodbc repository, delete all the files in the top-level /dist directory (create the /dist directory if necessary).

   The /dist directory will be used to store all the build files before uploading to PyPi. In principle, any directory could serve this purpose but by convention /dist is used.

5. From the Github Actions page, find the chosen commit in the "Build the release artifacts" workflow and download all the zipped artifacts prefixed "sdist" and "wheels" into your /dist directory.

   https://github.com/mkleehammer/pyodbc/actions/workflows/artifacts_build.yml

6. In your /dist directory, unzip the sdist/wheels zip files to retrieve the sdist/wheel files within them. Delete the zip files.

7. From the command prompt, navigate to the top-level pyodbc directory and upload the contents of the /dist directory to the Test PyPi:

   twine upload -r testpypi dist/*

   Check Test PyPi (https://test.pypi.org/project/pyodbc/) to make sure the files were uploaded successfully.

8. If the upload to Test PyPi is successful, upload the same contents of the /dist directory to the real PyPi.

   Bear in mind, you get only one shot at this! You can't replace files in PyPi, so make sure you get this right first time:

   twine upload dist/*

   Check the real PyPi (https://pypi.org/project/pyodbc/) to make sure the files were uploaded successfully.

9. Create release notes from the Github portal, based on the git tag created earlier. This will be the main source of information about the release so make it reasonably comprehensive.

   https://github.com/mkleehammer/pyodbc/releases

10. Finally and optionally, increment the VERSION constant in setup.py to the next release, and commit. For example, from "5.2.0" to "5.3.0". This helps to ensure there's no confusion about newly-generated build files.

    And that's it!