|
| 1 | +# Patch Releases |
| 2 | + |
| 3 | +Occasionally, we need to release versions of CesiumJS prior to our typical [monthly train releases](../README.md). This can arise because of a critical regression or compatibility issue with the published dependency versions. When this is necessary, we publish a **patch** release[^1]. Tools like npm which use Semantic Versioning will usually use this new version of the package the next time a user runs `npm install` without the user needing to opt-in. |
| 4 | + |
| 5 | +[^1]: See ["About semantic versioning" on docs.npmjs.com](https://docs.npmjs.com/about-semantic-versioning) |
| 6 | + |
| 7 | +## Publishing a patch version |
| 8 | + |
| 9 | +This process is based on an abbreviated version of the [monthly release guide](../README.md). Familiarity with our typical release process is recommended, but not required. |
| 10 | + |
| 11 | +### 1. Create a new branch from the base tag |
| 12 | + |
| 13 | +If no additional commits (besides the intended patch fix) have been merged into `main` since the monthly release, you may create a new branch from `main` and skip step 2. Otherwise, proceed with the steps below. |
| 14 | + |
| 15 | +- Checkout a git tag for the base branch– i.e., use `1.123` in place of `<git-tag>` for the previous monthly release, or `1.123.1` for a subsequent patches applied in the same month. |
| 16 | +- From this branch, create a new branch with any unique `<branch-name>`. |
| 17 | + |
| 18 | +#### Commands |
| 19 | + |
| 20 | +```sh |
| 21 | +git checkout <git-tag> |
| 22 | +git checkout -b <branch-name> |
| 23 | +``` |
| 24 | + |
| 25 | +### 2. Cherry pick relevant commits |
| 26 | + |
| 27 | +- Use [`git-cherry-pick`](https://git-scm.com/docs/git-cherry-pick) one or more times to apply select commits to the current branch |
| 28 | +- As necessary, resolve any merge conflicts, add, and continue. |
| 29 | + |
| 30 | +#### Commands |
| 31 | + |
| 32 | +```sh |
| 33 | +git cherry-pick <commit-hash> |
| 34 | +``` |
| 35 | + |
| 36 | +### 3. Bump the release version |
| 37 | + |
| 38 | +Use [npm `version` with the `patch` command](https://docs.npmjs.com/cli/v11/commands/npm-version) to bump the version of each workspace and the root package– e.g., `npm version patch --no-git-tag-version` |
| 39 | + |
| 40 | +#### Commands |
| 41 | + |
| 42 | +```sh |
| 43 | +npm version patch --ws --no-git-tag-version |
| 44 | +npm version patch --no-git-tag-version |
| 45 | +``` |
| 46 | + |
| 47 | +### 4. Update `CHANGES.md` |
| 48 | + |
| 49 | +- In [`CHANGES.md`](../../../CHANGES.md), create a new header with the version string of root package from the previous step and the date of the release— e.g., if the version string from the previous step is `1.123.1`, `CHANGES.md` should read: |
| 50 | + |
| 51 | +```md |
| 52 | +# Change Log |
| 53 | + |
| 54 | +## 1.123.1 - 2025-07-15 |
| 55 | + |
| 56 | +### @cesium/engine |
| 57 | + |
| 58 | +... |
| 59 | +``` |
| 60 | + |
| 61 | +- Move any relevant items in the list to the new header in `CHANGES.md`. |
| 62 | +- Delete any empty headers. |
| 63 | +- Ensure each change is nested in the section for the relevant workspace. |
| 64 | +- Commit any staged changes and push to your branch. |
| 65 | + |
| 66 | +### 5. Release build and sanity test |
| 67 | + |
| 68 | +While the full extent of typical release testing is not required, at minimum, create a release build and run the release tests. |
| 69 | + |
| 70 | +- Make sure the repository is clean `git clean -d -x -f --exclude="/Specs/e2e/*-snapshots/"`. **This will delete all files not already in the repository, excluding end to end testing snapshots.** |
| 71 | +- Run `npm install`. |
| 72 | +- Make sure `ThirdParty.json` is up to date by running `npm run build-third-party`. If there are any changes, verify and commit them. |
| 73 | +- Create the release zip `npm run make-zip`. |
| 74 | +- Run tests against the release `npm run test -- --failTaskOnError --release`. |
| 75 | +- Run [Sandcastle](http://localhost:8080/Apps/Sandcastle/index.html) and verify functionality from the patch is working as expected. |
| 76 | + |
| 77 | +### 6. Push and tag the release commit |
| 78 | + |
| 79 | +- Push your commits to the _current_ branch. |
| 80 | +- Create and push a [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging), e.g., if the version string from previous steps is `1.123.1`, run: |
| 81 | + - `git tag -a 1.123.1 -m "1.123.1 release"` |
| 82 | + - `git push origin 1.123.1` (this assumes origin is the primary cesium repository; do not use `git push --tags` as it pushes all tags from all remotes you have on your system) |
| 83 | + |
| 84 | +#### Commands |
| 85 | + |
| 86 | +```sh |
| 87 | +git push |
| 88 | +git tag -a <version-tag> -m "<release-description>" |
| 89 | +git push origin <version-tag> |
| 90 | +``` |
| 91 | + |
| 92 | +### 7. Publish |
| 93 | + |
| 94 | +#### a. Publish to npm |
| 95 | + |
| 96 | +Continue with the normal `publish` command; There is no need to tag this differently than a typical release version. |
| 97 | + |
| 98 | +- Use `npm publish --ws` in the repository root to publish the workspaces. |
| 99 | +- Use `npm publish` to publish the root package. |
| 100 | + |
| 101 | +#### b. Publish to the website |
| 102 | + |
| 103 | +**_Often, as is the case with issues arising from published dependency versions, a patch release only needs to be published to npm and does not need to be deployed to cesium.com. If that is the case, skip step 7b and proceed to step 8._** |
| 104 | + |
| 105 | +- Check out the `cesium.com` branch. |
| 106 | +- Merge the new release tag into the `cesium.com` branch with `git merge origin <tag-name> --ff-only`. |
| 107 | +- Push the branch with `git push`. CI will deploy the hosted release, Sandcastle, and the updated doc. |
| 108 | + |
| 109 | +### 8. Port the updates back to `main` |
| 110 | + |
| 111 | +It's important that the latest version info goes back into the `main` branch to streamline future releases. |
| 112 | + |
| 113 | +- Checkout `main` and pull the latest updates: |
| 114 | + - `git checkout main` |
| 115 | + - `git pull` |
| 116 | +- Checkout your patch release branch: |
| 117 | + - `git checkout <release-branch>` |
| 118 | +- [Optional] Create a new branch to perform the merge: |
| 119 | + - `git checkout -b <branch-name>` |
| 120 | +- Merge `main`, resolving any conflicts, particularly in `CHANGES.md`. Ensure the patch release _is_ included in the release notes, and ensure the specific patch fix descriptions are only listed once under the patch release. |
| 121 | + - `git merge main` |
| 122 | + - `git add .` |
| 123 | + - `git diff main` |
| 124 | +- Commit and push your changes: |
| 125 | + - `git commit -m "sync version info"` |
| 126 | + - `git push --set-upstream origin <branch-name>` |
| 127 | +- Open a new PR with the **priority - next release** label |
| 128 | + |
| 129 | +### 9. Announce the release |
| 130 | + |
| 131 | +Once the packages have been successfully published to npm, notify the interested developers that the release has been completed. This may include adding a comment to relevant GitHub issues that a fix has been published. |
0 commit comments