Skip to content

Latest commit

 

History

History
65 lines (48 loc) · 8.24 KB

How to create a release.md

File metadata and controls

65 lines (48 loc) · 8.24 KB
Raw

How to create a Pluto.jl release

What is a Pluto release?

A Pluto release is a collection of the following things: (most are generated automatically)

  • A release entry point in the General Julia registry: people who installed Pluto using Pkg can do Pkg.update() to get it
  • A git tag
  • A GitHub release with release notes: useful for our superfans, for future Pluto devs and for documenting a breaking API change
  • A new collection of featured notebooks!
  • An offline-ready bundle of our frontend: fonsp/Pluto.jl#1561
  • An update to https://github.com/fonsp/pluto-on-binder, our repository designed to run a Pluto server on binder, used "headless" by all HTML exports generated from the Pluto GUI. A git tag is created that matches the Pluto version numbers

Following the steps below will make sure that all of these are in place!

When to release?

After a security fix: release immediately and make it a RECOMMENDED release (more on this below).

If there was an important bug fix, release soon.

If there was a large change that still needs more debugging, don't release for a little while. Example is fonsp/Pluto.jl#844 merged on June 11 2021, released on July 6 2021.

  • This can be avoided by hiding the feature behind a flag, and disabling it by default, and later enabling it by default. Example is fonsp/Pluto.jl#1029 (comment)
  • If there is a security issue / crucial bug fix that needs to be released during an unstable period, create a branch off the last release, add the fix and release from there. Example is (can't find it but it happened sometimes)

Other than that, we try to have long periods without a release for one funny reason: to make binder faster! If lots of people use the same version of Pluto, then all the HTML files they generate will use the same version of pluto-on-binder. This makes binder launches fast. So it's fine to do a release if there was one yesterday, but if the last release was a week ago, then it might be nicer to wait.

Step by step

Make sure that you are available to fix any problems during the next two hours.

Here is how you release a new Pluto.jl version:

  1. Run the new version of Pluto, and play around with a sample notebook to make sure that everything works.
    • Important: Open a couple of featured notebooks to check that they display correctly. We do not have automatic tests to see if the featured notebooks work. If the structure of the statefile changed, this can cause them to fail without a CI failure. You may need to follow these instructions to update them.
  2. (Optional, but nice. Maybe we can automate this one day...) The following sample notebooks have an embedded Manifest.toml: Plots.jl, PlutoUI.jl and JavaScript. Using Julia 1.6 (not 1.7), open these notebooks, and click the "update" button to update their packages. Commit these changes to the main branch. (example) If these notebooks are very outdated, then users will have to download many packages twice: once to open the sample notebook, a second time if they use (newer versions of) those packages in a new notebook.
  3. Edit the Project.toml file to bump the version number.
  4. Commit
  5. Wait for tests to pass.
  6. We have a GH Action that takes the code on the main branch, bundles the JS files for offline supports, and writes to the release branch. Go to the release branch, and wait for this commit to arrive. It should take 3 minutes. (example)
  7. Find the commit that "GitHub Actions" just created on the release branch. Wait for the test on that commit to pass. These additional tests run the frontend tests on the bundle, with a disabled internet connection. This tests that the bundle is correct, and that we have offline support.
  8. Click on that commit (on the release branch, authored by "GitHub Actions"), and comment @JuliaRegistrator register() in the commit comments (example). Some notes:
    • Triggering a release from the release branch instead of main means that we will have offline support!
    • Important: from this point on, until the last step, there should be no commits to main. Committing to main would trigger the bundler to create a new release commit, overwriting the one that you are registering. This prevents the commit from being tagged later (see the release explainer at the bottom of this document), which means disaster. This is a flaw in our release process, fonsi will fix it after the summer. For safety, you could temporarily Disable the Bundle workflow at this point, and re-enable it after the release has been tagged.
  9. While waiting for the version to be merged into General, you can still cancel it if you changed your mind: comment Hold on! on the General PR. You can also trigger @JuliaRegistrator register() on another (newer) commit with the same version number, and this will replace the PR. Edit your previous comment to include [noblock], and the clocks will start again.
  10. Wait for the new version to be merged into General (example)
  11. Wait for TagBot to tag a new release on fonsp/Pluto.jl (example)
  12. Wait for this robot to update pluto-on-binder and tag a new version (but no release i think) (example)
  13. Use the "Export to HTML" button inside Pluto to generate an export, and open it. This should work (i.e. the jsdelivr CDN should serve the new Pluto version)
  14. Click the "Edit or Run this notebook" button, and click Binder. This will trigger a binder build.
  15. If you know how, trigger binder builds for all mybinder.org providers.

If this is a RECOMMENDED release (i.e. we want all users to get a pop-up to update Pluto, we only do this for crucial bug fixes):

  1. Wait at least 4 hours before marking a release as recommended, since there is a delay between the General registry and Julia's package servers.
  2. Open the GitHub release notes and edit the description to contain Recommended update (example)

If you have access to the plutojl.org account for cloudflare.com:

  1. Go to Rules
  2. Look for the Page Rule with a hard-coded Pluto version, and change it to the new latest version

How does the release branch work?

The bundler action runs for every commit to main, it runs the bundler, generating the frontend-dist folder. This folder is normally gitignored, but the bunlder action will force add, force commit, and force push to the release branch. It also did a hard reset to main, which means that the release branch is always an exacty copy of the main branch, plus one commit, which adds the frontend-dist folder.

This hard reset strategry means that old "bundle" commits disappear, and will eventually be garbage collected by GitHub. This avoids a very big .git folder. Now, this would be a problem: people won't be able to install released versions... But! Because we automatically tag every released commit, all of the "bundle commits" (like https://github.com/fonsp/Pluto.jl/commit/3633cae1e9aa7c21db83857eaa397b15fd208a40 ) that were released are also tagged. A tagged commit is never garbage collected, even though they no longer belong to any branch.