Step 1. Install minchin.releaser.

The simplest way is to use pip:

pip install minchin.releaser

This will also install all the other packages minchin.releaser depends on.

You will also want to add minchin.releaser to the list of your project’s requirements.

Step 2. Create a tasks.py file.

This is where invoke determine was tasks are available to run. This file should be created in the root folder of your project. If you are not using invoke for other tasks, this file can be four lines:

# tasks.py

try:
    from minchin.releaser import make_release
except ImportError:
    print("[WARN] minchin.releaser not installed.")

# your other Invoke tasks...

To confirm that this is working, go to the command line in the root folder of your project, and run:

$ invoke --list

which will now list make-release as an available task.

Step 3. Configure your project.

Project configuration is actually invoke configuration, so it is stored in the invoke.yaml folder in the project root (or anywhere else invoke can load configuration from) under the releaser key.

Available sub-keys:

module_name

(required) the name of your project. It is assumed that your project’s version number is importable at module_name.__version__ (see project assumptions).

pypi_name

(optional) the name of your project as uploaded to PyPI. This only needs to be set if it differs from module_name.

here

(required) the base location to build your package from. To set to the current directory, set to .

docs

(required, but can be set to None) the base documentation directory. This is relative to here.

test

(required, but can be set to None) the base test directory. This is relative to here.

source

(required) the base directory of your Python source code. This is relative to here.

changelog

(required, but can be set to None) the location of your changelog file. This is relative to here.

changelog_version_line

(optional) the line added to your changelog to mark a release. Use the placeholders {version} and {date} (as YYYY-MM-DD). Defaults to (to match the sytle of the `releases <https://github.com/bitprophet/releases>`_ Sphinx extension):

- :release:`{version} <{date}>`

version

(required) the location of where your version string is stored. This is relative to here.

test_command

(required, but can be set to None) command, run from the command line with the current directory set to here, to run your test suite.

version_bump

(optional) default level to bump your version. If set to none, this will be requested at runtime. Valid options include major, minor, bug, and none.

extra_packages

(optional) Used to install packages before installing your module from the server. Useful particularly for packages that need to be installed from cache (rather than re-downloaded and compiled each time) or for packages that are not available on the test PyPI server. Valid server keys are local, test, and pypi. Under the server key, create a list of the packages you want explicitly installed.

(vendorize keys are not listed here.)

Step 4. Set up Invoke command shell (Windows).

Minchin dot Releaser runs certain commands at the command line. Invoke, regardless of platform, tries to run these on /bin/bash which doesn’t exist in Windows and thus these commands fail.

To fix this, create a .invoke.yaml file in the root of your user directory (so the file is C:\Users\<your_username>\.invoke.yaml) and add:

run:
    shell: C:\Windows\system32\CMD.exe

Step 5. Set up twine configuration.

Create or modify $HOME/.pypirc to include the testpypi server:

[distutils]
index-servers=
    pypi
    testpypi

[testpypi]
repository: https://test.pypi.org/legacy/
username: your testpypi username

Minchin dot Releaser is automated, and so needs access to your password. This can be done using keyring. Keyring can be installed by pip and then passwords are added from the command-line.

$ pip install keyring
$ keyring set https://test.pypi.org/legacy/ your-username
$ keyring set https://upload.pypi.org/legacy/ your-username

See Twine Keyring Support for more details.

Step 6. Register your package on PyPI.

(On the new infrastructure, this no longer needs to be done explicitly. Just upload your package.)

Step 7. Upload your package.

$ invoke make-release

And then work through the prompts. If this process breaks half-way through, you can re-start.

In particular, many packages are not available on the test version of PyPI, and will need to iteratively be added to the configuration under the extra_packages.test key.