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 release 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. Set the pyodbc package version. Check the package version for the new release in the pyproject.toml file (see the version field under [project]). If that value is not correct, change it, commit and push. 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 (and the commit from the previous step), but it can theoretically be any commit. Take a note of the commit number ("SHA").

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

3. Create a git tag for the chosen commit. This tag should typically be exactly the same as the package version from the first step. In your local pyodbc repository, create the annotated tag with:

   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. Build the artifacts. From the Github Actions page, navigate to the "Build the release artifacts" workflow page:

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

   Click on the gray button "Run workflow" (on the right) and choose the relevant tag/commit from the revealed dropdown. You will probably want to choose the tag you created in the previous step. Click on the green button "Run workflow". GitHub Actions will then start to build all the release artifacts. Wait for this to complete, it takes about 10 minutes. You can follow progress by clicking on the new workflow link (with the brown dot next to it).

5. Download the release artifacts. 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 release files before uploading to PyPi. In principle, any directory could serve this purpose but by convention /dist is used.

   At this point, you will probably still be in the correct Github Actions workflow run page already from the previous step, but if necessary, navigate to the Github Actions "Build the release artifacts" page, find the relevant tag, and click on the workflow run to see the details of the run.

   Scroll to the "Artifacts" section at the bottom of the page and download all the zipped artifacts prefixed "sdist" and "wheels" into your /dist directory.

6. In your /dist directory, unzip the sdist/wheels zip files. Delete the zip files. At this point, this directory should have nothing in it except the contents of the zip files.

7. (optional) Upload to Test PyPi. 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. Upload to PyPi. From the command prompt, navigate to the top-level pyodbc directory and upload the 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 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. (optional) Finally, increment the version field in pyproject.toml 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 release files generated after this release.

    And that's it!