Maintainer page

Making a new release

Prepare

For any major dependencies that have clear version-support/end-of-life policies, ensure that we specify a version that will not reach end-of-life within 6 months of our date-of-release. (For now, this is only NumPy, via NEP29's guidance.)

Check that all CI checks are passing.

To prepare a new release, first checkout a fresh copy of Gensim:

cd /tmp
git clone [email protected]:RaRe-Technologies/gensim.git && cd /tmp/gensim
git remote add upstream [email protected]:RaRe-Technologies/gensim.git  # expected by prepare.sh
pip install -e .
pip install requests  # expected by update_changelog.py

And then run:

$ export RELEASE=1.2.3  # The version you'll be releasing
$ bash release/prepare.sh $RELEASE

The above command will do the following for you:

• Check out a release branch
• Bump versions
• Update the change log

Once the script completes, you'll have the chance to make other changes manually if anything isn't 100% correct.

For example, if updating README.md, then update LONG_DESCRIPTION in setup.py

Some things to check:

• Does CHANGELOG.md contain a section for the new release?
• Does CHANGELOG.md contain a complete list of merged PRs?
• Does CHANGELOG.md contain a full list of deprecated features?
• Do setup.py, docs/src/conf.py and gensim/__init__.py list the new release as the version?

Merge

Run:

bash release/merge.sh

The above command will:

• merge the release branch into develop
• merge develop into master
• tag master with the appropriate release tag

Push

First, double check that everything is in order. This your last chance to make a mistake without anybody noticing.

Run:

bash release/push.sh

The above command will push your changes to github, including the new tag.

Add text description in https://github.com/piskvorky/gensim/tags (typically, copy-paste head of changelog).

Build wheels for all platforms

Our CI will build wheels for the release. We use Github Actions (example) to build our wheels. Once the build is successful, these wheels will end up on our S3 bucket. We'll use the wheelhouse project to download these wheels to your local dev machine and then publish them to PyPI. Before you do that:

1. Confirm the CI workers are done at https://github.com/RaRe-Technologies/gensim/actions, and that all wheels built successfully:

2. Confirm the wheels made it to http://gensim-wheels.s3-website-us-east-1.amazonaws.com/ - look for the particular release in the filenames.

Then, to download all wheels + generate sdist:

pip install wheelhouse_uploader twine
python setup.py sdist fetch_artifacts

Upload all wheels to PyPI.

⚠️ The following command will make this release "public". From then on, pip install -U gensim will install this release!

twine upload dist/gensim-"$RELEASE"*

Check that the wheels have been uploaded properly to https://pypi.org/project/gensim/#files. You can then delete them from S3 to save on AWS costs:

aws --profile smart_open s3 rm --recursive s3://gensim-wheels/

The AWS bucket automatically deletes older releases, so the above step is not strictly necessary.

Build for conda-forge

Update coda-forge repository, see commit example.

More information about conda-forge is available in conda-forge/gensim-feedstock/.

Update public documentation

Update the documentation at http://radimrehurek.com/gensim:

python setup.py build_ext --inplace
make -C docs/src html upload

Update Gensim version to report the next release

Us as developers, as well as people installing the "bleeding edge" from Github, shouldn't see the last released version in gensim.__version__. It's misleading. Instead, change the Gensim version to report the next expected release, e.g. 4.1.1.dev0 if the last released version above was 4.1.0.

Use the bump_version.py script to update the version consistently in all places, and commit the result to develop.

Let the world know!

Tweet about the successful release 👍