.. _nbconvert_release: 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. .. _GitHub no milestones: https://github.com/jupyter/nbconvert/pulls?utf8=%E2%9C%93&q=is%3Amerged%20is%3Apr%20no%3Amilestone%20 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): .. code:: bash github-stats --milestone=$VERSION --since-tag $LAST_VERSION --links .. _ghpro: https://github.com/mpacer/ghpro/tree/alternate_styling 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. #. New Features #. Deprecations #. Fixing Problems #. 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: .. code:: bash 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 ------------------ #. Update the :doc:`changelog ` to account for all the PRs assigned to this milestone. #. 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. #. Commit and tag the release with the current version number: .. code:: bash git commit -am "release $VERSION" git tag $VERSION #. You are now ready to build the ``sdist`` and ``wheel``: .. code:: bash pip install build python -m build . #. 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. .. code:: bash twine upload dist/* #. 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. .. _conda-forge-nbconvert: https://github.com/conda-forge/nbconvert-feedstock Release the new version ----------------------- Push directly on main, including --tags separately .. code:: bash 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).