Release a Version

Test your package:

  1. Run the tests (in PyCharm and/or with GitHub actions).

  2. Check your coverage (locally in cov/index.html and/or on Codecov) and add tests if necessary.

In PyCharm:

  1. Check that all new classes are in the file __init__.py and in the Reference section of the documentation.

  2. Generate the documentation (in PyCharm and/or with GitHub actions) in order to check that it is working.

  3. If you were working on a secondary branch (which is desirable), do what you have to do: pull request to "main" or "master", etc.

  4. Ensure that you are now in your default git branch ("main" or "master").

  5. Update the file HISTORY.rst. Stick to pure .rst syntax: never use Sphinx' specific directives such as :class:`MyClass`.

  6. In PyCharm's terminal, do one of the following (except for the first release):

    • bumpversion patch (version x.y.z → x.y.(z+1)) when you made a backwards-compatible modification (such as a bug fix).

    • bumpversion minor (version x.y.z → x.(y+1).0) when you added a functionality.

    • bumpversion major (version x.y.z → (x+1).0.0) when you changed the API. Note: in versions 0.y.z, the API is not expected to be stable anyway.

  7. Commit/push.

On GitHub's website:

  1. Go to “releases”.

  2. Select “Draft a new release” or “Create a new release”.

  3. Add a tag name as in HISTORY.rst, e.g. 0.1.0.

  4. Add a release title as in HISTORY.rst, e.g. First release.

  5. Add release notes as in HISTORY.rst, e.g. * First release on PyPI..

  6. Select “Publish release”.

After a few minutes, GitHub has finished the built and it is deployed on PyPI. If you want to check, search for your package name on PyPI and check that the version number is correct. Note that the PyPI badge may take several more minutes before being updated.

If the Deployment on PyPI Fails...

Check that the readme will be correctly rendered on PyPI.

In a terminal:

python setup.py bdist
twine check dist/the_name_of_the_file.zip

where the_name_of_the_file must be replaced by the relevant file name.

Add a Module (= a File)

Typically, this is a file sub_package\my_class, containing the class MyClass.

  1. In the file __init__.py: add the shortcut.

  2. In the directory reference of the documentation: add the auto-documentation.

Use a Third-Party Package

For example, you want to use Numpy in your module.

  1. Open the file setup.py.

  2. In the list requirements, add the name of the package (e.g. 'numpy').