Developer Doc: Creating a New Release

setup.py Changes

Update the version string: `version="x.y.z".

init.py Changes

Change the version number in the __init__.py file in the root cadquery directory: __version__ = "x.y-dev" becomes __version__ = "x.y.z"

doc/conf.py Changes

Update the sphinx doc short and full version strings. version="x.y" release="x.y.z".

doc/conf.py will pick up the version change automatically now(todo: verify this is working as expected in the next release 2.5).

Update changes.md

All of the changes since the last release need to be documented.

Create a PR

Create a PR for the release changes to give other devs and the broader community the opportunity to comment.

Merge PR

Just what the section title says.

Publish to PyPI reference

Change to the root of your local copy of the CadQuery repo.

1. Make sure pip is the latest version.

pip install --upgrade pip

2. Install the latest build package from PyPA.

pip install --upgrade build

3. Perform the build.

python -m build

4. Make sure that a dist directory was created with a .tar.gz file in it and a .whl file.

ls dist

Example listing for CadQuery version 2.2.0:

5. Ensure that the dependencies are included by opening the wheel file with an archive manager and making sure that all of CadQuery's dependencies are included in cadquery-2.x.y.dist-info/METADATA as Requires-Dist directives. If they are not, try creating a fresh venv environment and retry the build. Do not use conda for building PyPI release packages.

6. Install the latest version of the twine package.

pip install --upgrade twine

7. Upload the dist to testpypi first to make sure the upload works correctly.

python -m twine upload --repository testpypi dist/*

You will be asked for a username and password. For the username use __token__ and for the password use the token you have generated at testpy under your user account settings.

8. Create a virtual environment and do a test install of the newly created release.

pip install --index-url https://test.pypi.org/simple/ --no-deps cadquery

You have to use --no-deps because the dependency packages are not available on TestPyPI. If everything worked without errors, you can now upload to the real PyPI.

9. Upload to the real PyPI

python -m twine upload dist/*

Test this final release in a virtual environment, and if there are no errors, you are done.

Tag the release

A Release should be created through the GitHub interface, and that release should be set to create a tag with the version number when it is published. So for CadQuery 2.2.0, the tag would be 2.2.0. The title of the release can be something simple, like CadQuery 2.x.y.

Tagging the release will automatically build the conda packages.

Change init.py, setup.py and doc/conf.py version back to dev

Example: __version__ = "2.2.0" would be become __version__ = "2.3-dev" to start next release cycle.

Update README.md and doc/installation.rst (if needed)

Review the installation instructions and update as necessary. Update/remove out of date references to "latest" release version. Check for out of date OCCT version pins.