How to cut a new release

Notes for myself.

Pre-Setup: Make a .pypirc file.

We're assuming that you're working on your local machine, and not in a dev container, as this step is intended to be a one-time setup per computer; if you're in a dev container, then skip over this step.

Shamelessly copied over from https://truveris.github.io/articles/configuring-pypirc/

Make a .pypirc file:

touch ~/.pypirc

Now edit the file:

nano ~/.pypirc

Paste in the following block

[distutils]
index-servers=
    pypi
    testpypi

[pypi]
username: brodan
password: xxxxxxxxxxxxxxxx

[testpypi]
repository: https://test.pypi.org/legacy/
username: brodan
password: yyyyyyyyyyyyyyyy

(If needed) Clone repository locally

If you do releases from your local machine, you can take advantage of the .pypirc setup earlier.

Be sure to set up the conda environment:

# Change directory to cloned repo
cd /path/to/pyjanitor  # change /path/to/pyjanitor to wherever you put cloned pyjanitor
# Create environment
conda env create -f environment-dev.yml
# Activate the development environment:
conda activate pyjanitor-dev
# Install pyjanitor into environment in development mode
pip install -e .

Make sure that all tests are passing on dev

If there's anything not passing, it must be fixed before a release can be cut.

On the GitHub main page for the repo, inspect the build status on Azure pipelines. The build stage "Run all pyjanitor tests" should be passing on the linux py37 and macOS py37 builds. (These are the only two builds that reliably fail when asked to fail; the Windows one keeps passing regardless.) If the notebooks are failing, so be it.

Decide what the new version number will be.

In X.Y.Z:

• X is the major version number, change only when there are breaking user-facing changes.
• Y is the minor version number, change only when functionality is added in a backwards compatible manner.
• Z is the patch version number, change when unsure, by default, or when there's minor changes that don't break anything.

While in the pre-1.x stage, we treat Y the same way as X.

Modify the CHANGELOG appropriately

Move everything "on deck" under a new header for the release.

Dry run bumpversion with the appropriate version bump

bumpversion is a tool that will help you automatically increment version numbers in software. The file .bumpversion.cfg is the config file that tells bumpversion where it's supposed to look for version numbers to increment.

Run the following command at the terminal from the pyjanitor directory:

# Enter into the pyjanitor directory
cd /path/to/pyjanitor
bumpversion --dry-run <PUT ONE OF: major, minor, patch> --allow-dirty --verbose

To be clear, there should be no angled brackets when you execute the command.

Inspect the output to make sure the changes that will happen are all correct.

Commit changes made to the CHANGELOG

git add .
git commit -m "Update CHANGELOG for release <put version number here>"

(No angled brackets, as usual!)

Actually run bumpversion with the appropriate version bump

bumpversion <PUT ONE OF: major, minor, patch> --verbose

bumpversion is configured to automatically commit changes. If the pre-commit hooks error out, fix whatever needs fixing and re-commit the changes.

Bumpversion is configured to automatically tag the release commit (with tag = True in .bumpversion.cfg). Verify that tagging is complete by typing in your terminal:

git tag | grep <new version number>

If the tag doesn't show up, then manually add a tag.

git tag -a v<NEW VERSION HERE>

Push changes with tags

git push && git push --tags

Cut release to PyPI

This should, in most cases, suffice:

make release

If it doesn't, open up the Makefile and execute each command in order under the release section.

Now merge the release into master

master branch is where we keep an "archival" of all releases. Intent is sort of like a backup to the tags.

git checkout master
git merge dev
git push --tags