Skip to content

Latest commit

 

History

History
113 lines (78 loc) · 6.14 KB

RELEASING.md

File metadata and controls

113 lines (78 loc) · 6.14 KB

The nteract Release Process

This document outlines logistics around how releases are handled in the nteract project, specifically the applications and npm packages within this repository.

Release Frequency

Production releases of nteract's npm packages, desktop app, and Jupyter extension will happen on a monthly cadence. Dev releases of nteract's npm packages will happen on a weekly basis. This segmentation allows users who are eager to grab the latest changes to do so at the existing pace of the weekly release cadence. Users who want more stable and less frequent releases can opt to consume from the production tag.

Release Process for Packages (dev)

lerna will be used to publish packages in the dev channel on a weekly cadence. To publish nteract's npm packages to the dev channel, you must complete the following steps.

  1. Ensure that you are on the master branch with the latest changes synced.
  2. Create a new branch with the release/yyyymmdd naming convention.
  3. Run the npx lerna publish --dist-tag=prerelease command in the root of the nteract repo.
  4. Follow the prompts to incremenet the versions of each package as appropriate.
    • Note that lerna will provide an output that lists the newly published versions of each package. Copy this as it will be relevant in later steps.
  5. Create a new Markdown file in the changelogs directory that captures the changes in this release.
    • The filename for this Markdown file should follow the YYYY-MM-DD.md naming convention.
    • The contents of the file should be based on the changelogs/changelog_template.md template file.
  6. Commit the changes with the new markdown file.
  7. Open a PR against master from your release/yyyymmdd branch. In the description of the PR, include the versions of the published npm packages that the lerna publish command provides.
  8. Merge the PR into master.

Release Process for Packages (production)

The release process for production packages is the same as the release process for dev packages. However, use npx lerna publish in Step #4 to publish the packages to the release channel.

After the release, you'll need to publish the latest version of the documentation sites. To publish the documentation site for the npm packages you will need to do the following.

  1. Ensure that you are added to the nteract team on now. You will need permissions in order to deploy the changes.
  2. Navigate to the root of the nteract repo directory.
  3. Run the yarn package:docs:deploy command. This will deploy a new instance of the site.
  4. Run the yarn package:docs:promote command. This will map the packages.nteract.io domain tothe newly deployed instance.

To publish the documentation site for the components, you will need to do the same steps as above. However, use the yarn docs:deploy and yarn docs:promote command respectively.

Release Process for Desktop App

The nteract desktop app is shipped on a monthly cadence. You can ship nteract desktop releases from any operating system, with one notable exception. Due to technical limitations, macOS releases can only be shipped on macOS. On the topic of macOS...

A special note for macOS

In order to build a signed copy with working auto-update, you will need to join the Apple developer program and get a certificate. The Electron docs have a document on submitting your app to the app store, you only have to get through to the certificate step. Note, that the certificate that you will need to download from the Apple Developer Program portal is called the "3rd Party Mac Developer Application" certificate.

All platform precursor

To be able to publish a release you'll need to generate a GitHub access token by going to https://github.com/settings/tokens/new. The access token should have the repo scope/permission. Once you have the token, assign it to an environment variable (on macOS/linux):

export GH_TOKEN="<YOUR_TOKEN_HERE>"

If you are on Windows, you can assign it as an environment using the following command in Command Prompt.

> setx GH_TOKEN "<YOUR_TOKEN_HERE>"

Note that setx will apply the environment variable in subsequence Command Prompt sessions.

Note: Make sure that your remote origin is set as git@github.com:nteract/nteract.git.

  1. Make sure the release is working by running yarn dist and testing the built app inside the ./applications/desktop/dist/ folder. You can build for all platforms using yarn dist:all.

  2. Double check that publish will really work by running yarn verifyBeforePublish first

  3. Run npx lerna publish to publish everything, which also runs the verification steps. You will have to pick versions for everything.

  4. Run the following to ship the built desktop app. This will generate the platform-specific assets and create a draft release on GitHub with the assets.

yarn ship:desktop
  1. From GitHub go to nteract's releases, verify everything works and edit the release notes. The name should follow our naming guidelines, namely that we use the last name of the next scientist in the list with an adjective in front. Example:
Last release: Avowed Avogadro
Next Scientist: Babbage
Next release: Babbling Babbage

You can pick alliterative adjectives by using the local dictionary and our friend grep:

$ cat /usr/share/dict/words | grep "^babb"
babbitt
babbitter
babblative
babble
babblement
babbler
babblesome
babbling
babblingly
babblish
babblishly
babbly
babby
  1. Once you're ready click "Publish release". On macOS and Windows, the update will be automatically downloaded and installed on user's machines.

Release Process for the nteract Jupyter Extension

To release the nteract Jupyter Extension, you will need to complete the following steps.

  1. Navigate to the applications/jupyter-extension directory within the nteract repo.
  2. Ensure that you are signed into PyPi on your machine and have permissions to publish the nteract_on_jupyter package.
  3. Run the yarn build:python command.
  4. Run the yarn upload:pypi command.