Releasing a new version

Releasing a new version

This project adheres to the Semantic Versioning specification by Tom Preston-Werner.

Releasing on Windows

Creating a release on windows is inadvisable due to the limitations for setting file permissions on the Windows file-system. On Windows 10 you can install a native Ubuntu shell to solve this problem. Within the shell first run:

$ umask 0022

To make sure file permissions will be set right. then Clone the repo (or pull the latest master) and follow the steps below to package the library. Uploading can be done from within Windows again if you prefer.

Requirements

Packages:

$ pip install -r requirements-all.txt
$ pip install wheel twine

GPG-Key:

Every maintainer should have a GPG key to sign the release. If you don't have one yet, create a new one. You can e.g. follow GitHubs guide to create a new GPG key, although you don't have to add the key to your account.

Moreover, the corresponding public keys should be made available to the users:

• Please add your public key to the public_keys directory with the appropriate name rename any existing keys ending on -current.gpg if appropriate. See also the README for more information.
• Please also add your public key to the website. For this, please edit the verify-releases.html file by adding a new <div> class="window">...</div> block with your key analogous to the existing ones.
• Optionally, you can also add your public key to a keyservers, e.g. keyserver.ubuntu.com.

Process

• Build documentation locally, fix any error & commit:

  $ make -C docs/ html

• Run tests, fix any error & commit:

  $ pytest -v

• Bump version:
  • telegram/_version.py
  • docs/source/conf.py
  • Replace all ocurrences of NEXT.VERSION by the correct version string in the docstrings
  • if the release includes a Bot API update, update README(_RAW).rst
  • if the release drops a Python version, update README(_RAW).rst and setup.py

• Log changes to:

  • CHANGES.rst

  Since writing adding the correct links is a bit tiresome, here is a little something to help you with it.

• Commit the version bump and CHANGEs.rst:

  $ git commit -a -m 'Bump version to v<VERSION>'

• Build source distribution:

  $ python setup.py sdist bdist_wheel

  This will also build PTB-Raw

• Upload to PyPI (-s to sign the package with your GnuPG key!):

  $ twine upload -s dist/python*

  This will also upload PTB-Raw

• Push all changes

  $ git push

• Create a new release:
  • Tag version: v<VERSION>
  • Release title: v<VERSION>
  • Description: <logs from CHANGES.rst>
  • create sha1 signature:

    sha1sum --binary dist/python-telegram-bot-X.Y.tar.gz > dist/python-telegram-bot-X.Y.tar.gz.sha1
    sha1sum --binary dist/python-telegram-bot-raw-X.Y.tar.gz > dist/python-telegram-bot-raw-X.Y.tar.gz.sha1

  • Upload the source distribution from pypi as binary attachment + asc (gpg signature) + sha1 (create it yourself).
• Trigger documentation rebuild:
• On Readthedocs dashboard trigger a build for stable release (you'd probably need to do it twice: check the git revision being built to make sure it's the right one).
• Close milestones for this version.
• Test in a clean virtualenv that pip install python-telegram-bot and pip install python-telegram-bot-raw work with the new version.
• If the doc-fixes branch got merged, create a new one.
• Merge the dev-wiki into the production wiki

Public Announcements

Please use the following channels/groups to announce a new version release:

• @pythontelegrambotchannel
• @pythontelegrambotgroup (Channel posts are automatically forwarded to here)

Channel posts should be a bit more verbose than the plain release notes. E.g. they can

• list the (non-dev-team) authors, who contributed to the release, maybe even for each PR
• have a short, informative description of new/changed features