Skip to main content
`Ctrl`+`K`

# Making an `nbconvert` release

This document guides a contributor through creating a release of `nbconvert`.

## Assign all merged PRs to milestones

Go to GitHub and assign all PRs that have been merged to milestones. This will be helpful when you update the changelog. If you go to this GitHub page you will find all the PRs that currently have no milestones.

## Gather all PRs related to milestone

ghpro can be used to extract the pull requests by call the following from nbconvert directory (will ask for an API token the first time):

>     github-stats --milestone=$VERSION --since-tag $LAST_VERSION --links

## Manually categorize tickets

Group the tickets by these general categories (or others if they are relevant). This usually a manual processes to evaluate the changes in each PR.

1. New Features

2. Deprecations

3. Fixing Problems

4. Testing, Docs, and Builds

## Collect major changes

From the tickets write up any major features / changes that deserve a paragraph to describe how they work.

## Update docs/source/changelog.rst

Copy these changes with the new version to the top of changelog.rst. Prior release changelogs can be used to pick formatting of the message.

## Check installed tools

Review `CONTRIBUTING.md`, particularly the testing and release sections.

## Clean the repository

You can remove all non-tracked files with:

>     git clean -xfdi

This would ask you for confirmation before removing all untracked files.

Make sure the `dist/` and `build/` folders are clean and avoid stale builds from previous attempts.

## Create the release

1. Update the changelog to account for all the PRs assigned to this milestone.

2. Update version number in `nbconvert/_version.py` and remove `.dev` from dev_info. Note that the version may already be on the dev version of the number you’re releasing.

3. Commit and tag the release with the current version number:

       git commit -am "release $VERSION"
       git tag $VERSION

4. You are now ready to build the `sdist` and `wheel`:

       pip install build
       python -m build .

5. You can now test the `wheel` and the `sdist` locally before uploading to PyPI. Make sure to use twine to upload the archives over SSL.

       twine upload dist/*

6. The conda-forge bot will automatically add a PR on your behalf to the nbconvert-feedstock repo. You may want to review this PR to ensure conda-forge will be updated cleanly.

## Release the new version

Push directly on main, including –tags separately

>     git push upstream
>     git push upstream --tags

## Return to development state

If all went well, change the `nbconvert/_version.py` back by adding the

  `.dev` suffix and moving the version forward to the next patch release number.

## Email googlegroup with update letter

Make sure to email jupyter@googlegroups.com with the subject line of “[ANN] NBConvert $VERSION – …” and include at least the significant changes, contributors, and individual PR notes (if not many significant changes).