Automate your releases with the Jupyter Releaser 🚀

Jeremy Tuloup
Jupyter Blog
Published in
5 min readOct 28, 2024

In the world of open-source software, releases ensure that the latest features, bug fixes, and improvements reach users promptly. However, the process of managing releases, especially for large projects, can be complex and error-prone. This is where Jupyter Releaser comes into play.

Jupyter Releaser is an automation tool developed by the Jupyter team to streamline and standardize the release process across Jupyter projects. Its goal is simple: reduce the manual burden on maintainers, ensure consistency, best practices, improve confidence, and eliminate the potential for human error.

😔 The Problem: Manual Release Processes

Many maintainers of libraries have experienced the pains of a manual release process:

  • Versioning Issues: Manually updating version numbers across multiple files can lead to inconsistencies and errors.
  • Changelog Generation: Creating and maintaining accurate changelogs can be time-consuming.
  • Publishing: Whether it’s for PyPI or npm, the process involves multiple steps that are easy to mess up, and requires maintainers to manage their own credentials and tokens.

These pain points are not just frustrating; they can also delay the release of new versions and introduce issues that affect the end-users.

🤩 The Solution: Jupyter Releaser

Jupyter Releaser automates and standardizes the release process, ensuring that everything from versioning to changelog generation and publishing is handled efficiently. It helps maintainers reduce toil and save time in the release process by enforcing best practices to:

  • Automate a changelog for every release
  • Verify the install and import of dist assets, such as Python wheels and npm packages, to ensure packaging is done correctly
  • Commit a message with hashes of dist files
  • Annotate the git tag in a standard format
  • Create a GitHub release with a changelog entry, and automatically populate a changelog file
  • Trigger a dry run publish on CI, to make sure the project is in a releasable state at any time
  • Consistently publish final packages to PyPI and npm

➡️ Getting Started with Jupyter Releaser

Step 0: Set up

Setting up a repository to use the Jupyter Releaser involves a few steps which are listed on this page of the documentation.

The first one is to create a GitHub app for the organization or profile that owns the repo, following this guide. Then continue with the steps in the documentation to fill in the values for the app.

To follow best practices it is also recommended to create a release environment on the repo to add the APP_ID variable and APP_PRIVATE_KEY secret.

If you publish a package to PyPI, you will also need to add a trusted publisher, which usually corresponds to the source repository.

For npm, don’t forget to specify a "publishConfig": { "access": "public" } to the package.json.

Finally, copy the prep-release.yml and publish-release.yml workflows from the example-workflows folder to your repository.

Quite a few steps, but you should now be ready to go! Fortunately this setup needs to be done only once per repository. If you release multiple projects hosted under the same organization, you can reuse the same GitHub app.

Again, feel free to refer to the documentation for the complete checklist.

Step 1: Prep Release

To start the release, go to the “Actions” tab of the repo and select “Step 1: Prep Release”. Open the “Run Workflow” dropdown and fill in the appropriate parameters.

Running the “Prep Release” workflow for a JupyterLab extension (speed x5)

Running this workflow will create a draft GitHub release with the generated changelog for the new version. You can edit the changelog by editing the release if needed. Don’t forget to click on “Save Draft” and not “Publish Release” if you make any changes! (the releaser will do the publishing in the next step)

Step 2: Publish Release

If the changelog and draft GitHub release look good, go back to the “Actions” tab and click on “Step 2: Prep Release”.

In most cases, you can leave the fields empty and the releaser will automatically publish the GitHub Release previously created.

Publishing the extension (speed x5)

Congrats, you just made your first release with the Jupyter Releaser! 🎉

Going further

Jupyter Releaser also provides a set of hooks and options, such as running an arbitrary command after a given step, or providing a custom strategy for versioning packages. This allows for great flexibility in more complex repositories.

Check out the documentation for more information.

🌐 How Jupyter Releaser Fits into the Jupyter Ecosystem, and beyond

Releases are moments of celebration in any project, a chance to deliver new features, enhancements, and bug fixes to users. But they shouldn’t be a source of stress. Jupyter Releaser makes releases smoother for maintainers across the Jupyter ecosystem and beyond.

Jupyter Releaser is now used for most of the projects in the Jupyter stack with great success, such a JupyterLab, Jupyter Notebook, Jupyter Server, ipykernel, and many more. It greatly simplified the previously complex JupyterLab release process, which used to take 30 minutes, and now boils down to clicking on just a few buttons on GitHub and waiting for the workflows to complete.

Although its name has “Jupyter” in it, the releaser is not limited to releasing Jupyter related projects only, If you maintain a simple Python or npm package, you can also use the Jupyter Releaser to publish your package(s) to PyPI, npm or both!

In the end, Jupyter Releaser can simplify your workflow and save you valuable time. Give it a try and check out the repo here to see how it can make software releases a breeze!

🙏 Acknowledgments

Many thanks to Steven Silvester for creating the Jupyter Releaser and helping with its adoption across the Jupyter stack.

Jupyter Releaser is an official Jupyter project, and the Jupyter Releaser maintainers would also like to thank the contributors in the Jupyter community who help improve the tool and provide feedback ❤️

Sign up to discover human stories that deepen your understanding of the world.

Free

Distraction-free reading. No ads.

Organize your knowledge with lists and highlights.

Tell your story. Find your audience.

Membership

Read member-only stories

Support writers you read most

Earn money for your writing

Listen to audio narrations

Read offline with the Medium app

Written by Jeremy Tuloup

Scientific Software Engineer at QuantStack, Jupyter Core Developer and Distinguished Contributor.

No responses yet

What are your thoughts?