|
| 1 | +# Releasing plotly.js |
| 2 | + |
| 3 | +This document is for maintainers who publish plotly.js. For contributor workflows, read [CONTRIBUTING.md](CONTRIBUTING.md) and [BUILDING.md](BUILDING.md). |
| 4 | + |
| 5 | +plotly.js follows [semver](https://semver.org). A release that adds functionality bumps the minor version. A minor version can go past 9, so `v1.22.0` is valid. |
| 6 | + |
| 7 | +Do every step below for each release, unless indicated otherwise. |
| 8 | + |
| 9 | +## Update README, CHANGELOG, and CITATION |
| 10 | + |
| 11 | +- Open [GitHub Actions](https://github.com/plotly/plotly.js/actions?query=branch%3Amain) and confirm that the `main` branch passes the tests |
| 12 | +- Run `git switch main && git pull` |
| 13 | +- Run `git status` and confirm that the working tree is clean |
| 14 | +- Run `git switch -c release-vX.Y.Z`, where `X.Y.Z` is the new version number |
| 15 | +- Run `npx check-node-version --node 22 --npm 10` to confirm the tooling versions before you install |
| 16 | +- Run `npm ci` |
| 17 | +- Run `npm run preversion` |
| 18 | +- Update the version number and the release date in [README.md](README.md) and [CITATION.cff](CITATION.cff). Skip this step for a release candidate. |
| 19 | + - Use find-and-replace in the README. The version number appears in three `https://cdn.plot.ly/plotly-X.Y.Z...` script URLs. |
| 20 | + - Update the `version` field and the `date-released` field in [CITATION.cff](CITATION.cff) |
| 21 | +- Run `npm run use-draftlogs` to copy the `draftlogs/` folder into [CHANGELOG.md](CHANGELOG.md) |
| 22 | + |
| 23 | + > [!NOTE] |
| 24 | + > `npm run use-draftlogs` accepts a filename that ends in `_add.md`, `_remove.md`, `_deprecate.md`, `_change.md`, or `_fix.md`. This will raise an error for any other name; rename files if necessary. |
| 25 | +
|
| 26 | +- Review [CHANGELOG.md](CHANGELOG.md). Replace the placeholder heading `## [X.Y.Z] -- UNRELEASED` with the real version number and release date. |
| 27 | + - Follow [keepachangelog](https://keepachangelog.com/) style |
| 28 | + - Correct typos and add missing entries and extra details |
| 29 | + - Open `https://github.com/plotly/plotly.js/compare/vX.Y.Q...main` to view every commit since the previous release `vX.Y.Q` |
| 30 | + - Confirm that every draftlog entry uses the link template `[[#1234](https://github.com/plotly/plotly.js/pull/1234)]` |
| 31 | + - Credit a community contributor at the end of that entry: **', with thanks to @<USERNAME> for the contribution!'** |
| 32 | +- Run `npm run empty-draftlogs` to empty the `draftlogs/` folder. Skip this step for a release candidate. |
| 33 | +- Run `git add -u . && git commit -m "chore: Updates for release vX.Y.Z"` |
| 34 | + |
| 35 | +## Update package.json and generate the release build |
| 36 | + |
| 37 | +- Run `npm version vX.Y.Z` from the repository root (for a release candidate, include the prerelease part, as in `npm version v4.2.0-rc.0`). The command runs these steps in order: |
| 38 | + - Run the `preversion` script, which tests the Node.js and `npm` versions, tests for `npm link`ed packages, and walks the dependency tree |
| 39 | + - Bump the version in `package.json` |
| 40 | + - Run the `version` script, which runs `npm run build` and then `git add -A lib dist build src/version.js` |
| 41 | + - `git commit`, with the message `'X.Y.Z'` |
| 42 | + - `git tag -a`, with the tag `'vX.Y.Z'` |
| 43 | + - The `postversion` script, which prints _Version bumped and committed. If ok, run: git push && git push --tags_ |
| 44 | + |
| 45 | + The build writes the `dist/` files: main bundles, partial bundles, locales, plot-schema, and geo assets. The build also writes the generated build files under [`build/`](build/README.md) and the package version file in `src/`. |
| 46 | + |
| 47 | + > [!NOTE] |
| 48 | + > The `npm ls` step inside `preversion` fails if the dependencies under `node_modules/` don't meet the requirements listed in `package.json`. Run `npm ci` to fix this issue. |
| 49 | +
|
| 50 | +- Run `git show HEAD` to review the commit |
| 51 | + - The output shows the new CDN bundle links and the new bundle sizes in `dist/README.md`, plus the new code in the dist bundles |
| 52 | + - Carefully review the new bundle sizes in `dist/README.md`. If a bundle size has changed unexpectedly, or the diff contains any other unexpected change, run `git reset --hard HEAD^` and `git tag -d vX.Y.Z` to undo the last commit and tag. Investigate the issue before proceeding. |
| 53 | +- If everything looks good, run `git push && git push --tags` to push the release branch and the release tag |
| 54 | +- Open a pull request against `main`, and assign the `no-draftlog` label |
| 55 | +- Wait for CI to pass, and get an approval |
| 56 | +- Merge the pull request with a merge commit |
| 57 | + |
| 58 | + > [!CAUTION] |
| 59 | + > Do not squash merge, since that will result in the tagged commit `vX.Y.Z` not being part of `main` |
| 60 | +
|
| 61 | +## Publish the release |
| 62 | + |
| 63 | +- Run `git switch main && git pull` after the pull request merges |
| 64 | +- Run `git branch --contains vX.Y.Z` and confirm that the output includes `main` |
| 65 | + |
| 66 | +### Publish to npm |
| 67 | + |
| 68 | +- Run `npm access list packages | grep plotly` to confirm your permission to publish the plotly.js packages |
| 69 | + - The output lists the Plotly packages that you can update |
| 70 | +- If that command returns no result, authenticate with npm: |
| 71 | + - Confirm your membership in the `plotly` npm organization. If you're not a member, contact the Libraries team for next steps. |
| 72 | + - Run `npm login` |
| 73 | + - Complete the authentication flow with the credentials for your account |
| 74 | + - Confirm in the terminal that the command finished |
| 75 | + - Run `npm access list packages | grep plotly` again, and read the list of Plotly packages |
| 76 | +- Run `npm pack --dry-run`. This shows what will be included in the published package without actually publishing. |
| 77 | + - Compare the package size against the previous release. An unexpected large change can be an indicator that something was added/removed that shouldn't have been. |
| 78 | + - Look for any files that don't belong in the release (usually at the project root level). If you find any, investigate why they're showing up. One resolution option is updating [.npmignore](.npmignore). |
| 79 | +- For a full release, run `npm publish`. This will publish the new version to the [npm registry](https://www.npmjs.com/package/plotly.js). |
| 80 | +- For a release candidate, run `npm publish --tag rc` instead |
| 81 | +- You will be prompted by npm to authorize publishing before proceeding. If you see an option to allow publishing without a challenge for the next few minutes, enable it. This will allow for easy partial bundle publishing that immediately follows completion of the `publish` step. |
| 82 | + |
| 83 | + > [!NOTE] |
| 84 | + > Before the `publish` step starts, the `prepack` and `postpack` scripts will run. These manage converting TS files to JS before packing and removing them after packing. After the `publish` step completes, the `postpublish` script will run. This kicks off `tasks/sync_packages.js`, which publishes the partial bundles. |
| 85 | +
|
| 86 | +### Publish to the Plotly CDN |
| 87 | + |
| 88 | +- Run `aws --version` and confirm that the output starts with `aws-cli/2` |
| 89 | +- If the command is not found, or the output shows version 1, install AWS CLI v2: |
| 90 | + - On macOS, run `brew install awscli` |
| 91 | + - On Linux or Windows, follow the [AWS CLI install guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) |
| 92 | +- Run `./tasks/cdn_publish.sh` to upload the new release files to the CDN bucket on S3 |
| 93 | +- If that step fails with an authentication error, run `aws configure` and enter the credentials for the plotly.js CDN bucket |
| 94 | + |
| 95 | +### Publish to GitHub |
| 96 | + |
| 97 | +- Open the [releases page](https://github.com/plotly/plotly.js/releases) and click "Draft a new release" |
| 98 | +- Select the tag for the release |
| 99 | +- Set the title to `vX.Y.Z`, the same text as the tag |
| 100 | +- Copy the description from the matching section of the CHANGELOG. Add extra context if necessary. |
| 101 | +- For a release candidate, select the "This is a pre-release" box |
| 102 | +- Click "Publish release" |
| 103 | + |
| 104 | +## Post-release tasks |
| 105 | + |
| 106 | +- Post a link to the release tag, `https://github.com/plotly/plotly.js/releases/tag/vX.Y.Z`, in the team announcement channels |
| 107 | + |
| 108 | +## Make a maintenance release |
| 109 | + |
| 110 | +At times it may be required to patch an older version of plotly.js (for a security fix, etc.). This example patches `v3.7.0` and publishes `3.7.1`. |
| 111 | + |
| 112 | +- Run `git show v3.7.0:package.json` and read the `preversion` script for the toolchain |
| 113 | + - A v3 tag needs Node.js 18. A v4 tag needs Node.js 22. |
| 114 | +- Run `git switch -c maintenance-v3.7.1 v3.7.0` |
| 115 | +- Run `npm ci` |
| 116 | +- Find the commits on `main` that fixed the bugs in question. This example uses `a34ad3`. |
| 117 | +- Run `git cherry-pick a34ad3`, fix the merge conflicts, and test the behavior |
| 118 | +- To apply several patches at once, use GitHub's `.patch` URLs with `git am` |
| 119 | +- Run `npm version patch`. The command bumps the version to `3.7.1`, runs `npm run build`, commits, and adds the tag `v3.7.1`. |
| 120 | +- Run `git show HEAD` to review the version commit |
| 121 | +- Run `git push && git push --tags` |
| 122 | +- Run `DRYRUN=1 npm publish --tag maintenance` |
| 123 | + - `DRYRUN` prevents publishing of the partial bundles via `tasks/sync_packages.js`. The patched bundle will still be published. |
| 124 | +- Run `npm view plotly.js versions` and confirm that the list holds `3.7.1` |
| 125 | +- Run `npm dist-tag ls plotly.js` and confirm that `latest` still points at the current release |
| 126 | + |
| 127 | +### Notes on maintenance releases |
| 128 | + |
| 129 | +- The `--tag` argument in the `npm publish` step is **very important**. Without that argument, the maintenance release takes the `latest` tag on npm. A clean `npm install plotly.js` then installs `3.7.1` instead of the current release from `main`. |
| 130 | +- Do not push a maintenance release to the CDN. This policy encourages every user to run the current plotly.js release. |
0 commit comments