Convert a Repo to Use Releaser#

Follow the steps below to convert a repository to use Jupyter Releaser for releases.

Prerequisites#

See checklist below for details:

  • Markdown changelog

  • Bump version configuration (if using Python), for example tbump

  • Access token with access to target GitHub repo to run GitHub Actions.

  • Access token for the PyPI registry

  • If needed, access token for npm.

Checklist for Adoption#

A. Prep the jupyter_releaser fork:

  • [ ] Clone this repository onto your GitHub user account.

  • [ ] Add a GitHub Access token with access to target GitHub repo to run GitHub Actions, saved as ADMIN_GITHUB_TOKEN in the repository secrets.

  • [ ] Add access token for the PyPI registry stored as PYPI_TOKEN. Note For security reasons, it is recommended that you scope the access to a single repository, and use a variable called PYPI_TOKEN_MAP that is formatted as follows:

    owner1/repo1,token1
    owner2/repo2,token2
    

    If you have multiple Python packages in the same repository, you can point to them as follows:

    owner1/repo1/path/to/package1,token1
    owner1/repo1/path/to/package2,token2
    
  • [ ] If needed, add access token for npm, saved as NPM_TOKEN.

B. Prep target repository:

  • [ ] Switch to Markdown Changelog

    • We recommend MyST, especially if some of your docs are in reStructuredText.

    • Can use pandoc -s changelog.rst -o changelog.md and some hand edits as needed.

    • Note that directives can still be used

  • [ ] Add HTML start and end comment markers to Changelog file - see example in CHANGELOG.md (view in raw mode)

  • [ ] Add tbump support if using Python - see example metadata in pyproject.toml

    • We recommend putting setuptools metadata in setup.cfg and using version = attr: <package_name>.__version__.

    • See documentation on setup.cfg metadata

    • If previously providing version_info like version_info = (1, 7, 0, '.dev', '0'), use tbump config like the one below:

[[tool.tbump.file]]
src = "jupyter_server/_version.py"
version_template = '({major}, {minor}, {patch}, "{channel}", "{release}")'

[[tool.tbump.field]]
name = "channel"
default = ""

[[tool.tbump.field]]
name = "release"
default = ""
  • [ ] Add a GitHub Actions CI step to run the check_release action. For example:

- name: Check Release
  if: ${{ matrix.python-version == '3.9' }}
  uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

Note The check release action needs contents: write permission.

  • [ ] If you would like the release assets to be uploaded as artifacts, add the following step after the check_release action:

- name: Upload Distributions
  uses: actions/upload-artifact@v2
  with:
    name: jupyter-releaser-dist-${{ github.run_number }}
    path: .jupyter_releaser_checkout/dist
  • [ ] Add a workflow that uses the enforce-label action from jupyterlab/maintainer-tools to ensure that all PRs have on of the triage labels used to categorize the changelog.

  • [ ] Update or add RELEASE.md that describes the onboarding and release process, e.g.

Release Workflow#

  • [ ] Set up a fork of jupyter-releaser if you have not yet done so.

  • [ ] Run through the release process, targeting this repo and the appropriate branch

  • [ ] Optionally add configuration to the target repository if non-standard options or hooks are needed.

  • [ ] If desired, add check_release job, changelog, and tbump support to other active release branches

  • [ ] Try out the Draft Changelog and Draft Release process against a fork of the target repo first so you don’t accidentally push tags and GitHub releases to the source repository.

  • [ ] Try the Publish Release process using a prerelease version before publishing a final version.

Backport Branches#

  • Create backport branches the usual way, e.g. git checkout -b 3.0.x v3.0.1; git push origin 3.0.x

  • When running the Publish Release Workflow, an automatic PR is generated for the default branch in the target repo, positioned in the appropriate place in the changelog.