Releasing a new version
=======================

.. contents::
    :local:
    :depth: 1

This repository uses `jupyter_releaser <https://jupyter-releaser.readthedocs.io/en/latest/>`_.

Prerequisites
-------------

- All PRs should be tagged with the appropriate milestone. Several of the
  releasing scripts depend on this being done.
- You will need a GitHub API key: https://github.com/settings/tokens

Backport PRs
------------

If you are making a bugfix release onto an existing branch (e.g. ``0.3.x``) then
you need to backport merged PRs from master onto this branch. To do this, check
out the release branch (e.g. ``0.3.x``) and then run the ``backport_pr.py`` script
from the ``tools`` directory.

First, use it to find the list of PRs that need to be backported (remember that
you should have tagged all PRs with the appropriate milestone)::

    ./tools/backport_pr.py 0.3.1

Second, use the script to backport the PRs one-by-one, in the order that they were
merged into master, for example::

    ./tools/backport_pr.py 0.3.x 123

If a lot of code has changed between the release branch and master, the patch
generated by the backport script may not apply. In this case, you will want to
either (1) edit the patch to make it apply (e.g., by fixing line numbers) or (2)
just apply the changes manually.

Update the changelog
--------------------

The :doc:`/changelog` is located at ``CHANGELOG.md``.

Get the list of PR
~~~~~~~~~~~~~~~~~~

Ideally, the :doc:`/changelog` should be updated as things are
changed. In practice, this doesn't always happen as people forget to include
changes to the changelog in PRs. However, the changelog should be fully
up-to-date at the time of a release. To ensure that it is up-to-date, filter
PRs on GitHub by the current milestone and make sure to include all major
changes. In addition, please include a full list of merged PRs, which can be
found using
`jupyter_releaser workflow <https://jupyter-releaser.readthedocs.io/en/latest/get_started/generate_changelog.html>`_.

Note that if you are updating the changelog on a release branch (e.g.
``0.3.x``), then you will need to also make the relevant changes on master.

Get the list of contributors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To get the list of contributors, you can use the ``contributor_list.py`` script
in the ``tools`` directory, for example::

    ./tools/contributer_list.py 0.3.0

This will print out the list of users who have submitted issues and/or PRs.
This list should then be included in the changelog.

Bump the version number
-----------------------

The version number is bumped using `tbump <https://github.com/your-tools/tbump>`_ :
``tbump <VERSION> --no-push``

The version number should have been changed in the following files :

- ``pyproject.toml``
- ``package.json``
- ``nbgrader/_version.py``
- ``src/assignment_list/index.ts``
- ``src/course_list/index.ts``
- ``src/validate_assignment/index.ts``

Rebuild the documentation
-------------------------

Regenerate all the documentation for this release by running :

    ``python tasks.py docs``

Make sure the linkcheck passes, and commit the results.

Make a PR
---------

At this point, make a pull request with the changes you have made so far. Make
sure all the tests pass. After this point, you shouldn't need to make any more
changes to the source: the remaining steps all have to do with building and
releasing packages and creating branches/tags on GitHub.

Clean all untracked files
-------------------------

Make sure there are no old files lying around the repository. First, see what
needs to be cleaned::

    git clean -ndx

After verifying this doesn't include anything important, clean them for real::

    git clean -fdx

Build and release the pip package
---------------------------------

To build the pip package, run the ``release.py`` script in the ``tools``
directory::

    ./tools/release.py

This will do a few things, including converting the README file to rst (so it
will display correctly on PyPI) and building the source distribution.
Afterwards, you can upload the package to PyPI with::

    pip install -U twine
    python -m twine upload dist/*

Create a git tag and possibly branch
------------------------------------

If this is a new major release, create a new ``.x`` branch. For example, if
this is the 0.3.0 release, create a branch called ``0.3.x``.

Additionally, regardless of whether this is a major release, create a tag for
the release. Release tags should be prefixed with ``v``, for example,
``v0.3.0``.

Create a release on GitHub
--------------------------

After pushing the tag (and branch, if necessary) to GitHub, create the actual
release on GitHub. To do this, go to
`https://github.com/jupyter/nbgrader/releases <https://github.com/jupyter/nbgrader/releases>`_
and click the button for "Draft a new release". Choose the tag you just created
and set the title as "nbgrader <tag>", where "<tag>" is the name of the tag
(e.g. v0.3.0). Put in the release notes, which should be pretty much the same
as what is in the changelog.

Build and release the conda packages
------------------------------------

The conda recipe has been moved to a separate repository ("feedstock") and now
publishes ``nbgrader`` to the ``conda-forge`` channel automatically via CI. The
conda forge buildbot should detect once you've created a tag and will
automatically create a PR for the new release within a short period of time
(might be up to an hour). Wait for this PR to happen, and then follow the
instructions in the `nbgrader-feedstock
<https://github.com/conda-forge/nbgrader-feedstock>`__.

Change to development version
-----------------------------

Bump the version again, this time to development. For example, if the release
was ``0.3.0``, then the new version should be ``0.4.0.dev``.

Use `tbump <https://github.com/your-tools/tbump>`_ again :
``tbump 0.4.0.dev --no-push`` (change the version number with the correct one)

As a reminder, the files concerned are :

- ``pyproject.toml``
- ``package.json``
- ``nbgrader/_version.py``
- ``src/assignment_list/index.ts``
- ``src/course_list/index.ts``
- ``src/validate_assignment/index.ts``
