Skip to content

Packaging Releasing Publishing

Jump to bottom
Wout edited this page Jan 17, 2025 · 8 revisions

How to do a release (update 2025)

  • update the version field in cpmpy/__init__.py
  • Update the release number in docs/conf.py
  • If it's a new year: Update the copyright field in docs/conf.py
  • Go to: https://github.com/CPMpy/cpmpy/releases -> Draft a new release
  • Add a new tag vx.y.z
  • You can now generate the release notes (all commits since last push)
  • Clean this up and try to be informative. (or ask an ai)
  • Save draft or release (only after committing the first 3 changes on main)
  • pypi will then automatically build a new version.

If you have done this before (if not, read lower first)

  • python3 -m pytest tests
  • edit changelog.md and cpmpy/init.py
  • `git commit -am "release X.Y.Z"
  • git push
  • optional: python3 -m build
  • gh release create vX.Y.Z -F changelog.md

Documentation related to packaging and pushing new versions to PYPI (pip). You will find information on how to make and configure setup.py in the references.

Requirements

You can either use PyPA build or setuptools

  • For PyPA build: python3 -m pip install --upgrade build this will relay on hot-installation of wheels.
  • For setuptools: python3 -m pip install --upgrade wheel
  • For both, install twine: python3 -m pip install --upgrade twine

Building

Very Important: Make sure to update the version field in cpmpy/__init__.py before building and releasing a new distribution. Also remember to push this commit before releasing.

As said, there are two ways to build, based on the existing packages at build time:

PyPA build

After installing PyPa build, run this command

  • python3 -m build

This command should output a lot of text and once completed should generate two files in the dist directory:

dist/
  cpmpy-X.X.X-py3-none-any.whl
  cpmpy-X.X.X.tar.gz

The tar.gz file is a Source Archive whereas the .whl file is a Built Distribution. Newer pip versions preferentially install built distributions, but will fall back to source archives if needed. You should always upload a source archive and provide built archives for the platforms your project is compatible with.

Setuptools

After installing PyPa build, run the following commands

  • To build the Source Archive python3 setup.py sdist
  • To build the Built Distribution python3 setup.py bdist_wheel

The results of these commands is similar to PyPA with two files in the dist folders

Documentation generation with sphinx

If you are doing documentation updates, you might want to check them first on your computer.

  • Make sure you have 'sphinx' and 'python3-sphinx-automodapi' installed on your system, as well as the python package m2r2
  • go into the 'doc/' directory
  • run 'make html', and it will generate html in '_build/html'

Releasing & Publishing the distribution to PyPI (pip)

Only first time (Already done: Ask Ahmed or Tias for the credentials)

The first thing you’ll need to do is register an account on Test-PyPI or PyPI. Then create a PyPI API token so you will be able to securely upload the project (this should happen only one time, the first time we upload to PyPI). Don’t close the page until you have copied and saved the token — you won’t see that token again.

Release

For releaseing there are two approaches, automatic using CLI and manual

Automatic

You need to have the github-cli installed in your computer.

  • First create a file e.g changelog.md and add the release detials in there (i.e. main points of what has been changed from last release)
  • Then simply run the following command to create and push a new release (e.g. example is version 0.5.5):
    gh release create v0.5.5 -F changelog.md

Manual (using the github interface)

Please follow the steps in this procedure to create a new release using the github web-interface.

Publishing to PyPI (pip)

For publishing, the best practice is to release first so that the pipeline of publishing the package can automatically push the new distribution to PyPi.

Automatically

  • First make a release of the last commit from the master branch.
  • Publish that release, on publishing the release a workflow will execute to publish the code as well.

Manually

Note To avoid having to copy and paste the token every time you upload, you can create a $HOME/.pypirc file and add the recieved credentials there:

[distutils]
	index-servers =
	    pypi
	    testpypi
[pypi]
	repository = https://upload.pypi.org/legacy/
  username = __token__
  password = <the token value, including the `pypi-` prefix>
[testpypi]
	repository: https://test.pypi.org/legacy/
  username = __token__
  password = <the token value, including the `pypi-` prefix>

To upload the package, use the following commands:

  • For Test-PyPI use twine upload --repository testpypi dist/*
  • For normal PyPI use twine upload --repository pypi dist/* or just twine upload dist/*

After uploading the PyPi package, you need still need to release to github, please follow the release documentations

References

Clone this wiki locally