Skip to content

Latest commit

 

History

History
52 lines (44 loc) · 4.94 KB

how-to-release.md

File metadata and controls

52 lines (44 loc) · 4.94 KB
Raw

How to release Realm JavaScript (with Actions)

In order to release Realm JavaScript, you need to be member of the Realm organization at Github.

It is possible to add a specific tag for the release on npm, for example to release a beta version without affecting the latest version users will install by default.

The procedure is:

  • Proof-read and mildly edit CHANGELOG.md.
    • You can edit it directly on github CHANGELOG.md or you can check out the latest main and edit it locally.
    • Verify that all fixes are linked to the associated pull request or issue.
    • If the release upgrades realm-core, review the realm-core release notes and copy over any relevant notes (edited to be JS-specific if appropriate) into our CHANGELOG.md.
      • Format the link as such: ([realm/realm-core#XXXX](https://github.com/realm/realm-core/issues/XXXX), since vX.Y.Z) where the since version refers to the Realm JS version.
    • Make sure the "Breaking Changes" and "Enhancements" sections are present if appropriate. These will be used to set the new version number, following semantic versioning.
    • NOTE: If the new version requires an update to React Native, then make sure it is at least a minor release, as to not unintentionally break realm for current users.
  • If you made changes: add, commit, and push the changes to the changelog:
    • git add CHANGELOG.md
    • git commit -m "Reviewed changelog"
    • git push origin main
  • Make sure that the latest commit to main has a green checkmark next to the commit ID, indicating that everything was built without errors. You may have to wait a few minutes for this, if you just made changes.
  • Click on the "Actions" tab, scroll down to "Prepare Release" (or first click on "Show more workflows..." if not visible), and click on that. If you have access to the Realm group, you will see a note "This workflow has a workflow_dispatch event trigger", with a "Run workflow" drop-down button.
  • In the drop-down, you can select a branch to release from. Choose main if you are making a normal release. If you are making a prerelease, choose your prerelease branch.
  • You can also choose the version number of the release you are making. Leave the field blank if you are making a normal release, as one will be autogenerated by examining the changelog. But if making e.g. a release candidate, enter the exact version to release and write it without a "v" prefix (e.g. 12.0.0-rc1).
  • Click on the green "Run workflow" button. This will create a release branch.
  • Click on the "Actions" tab again. After a minute or so, you will see several actions running on the "Prepare for X.Y.Z" commit of the release branch. Wait for them to complete.
  • Make any changes to the release branch that you feel are necessary. This is also a good point to ask for reviews and manual testing.
  • Wait for all the tests on the new release branch to pass.
  • DO NOT MERGE THE RELEASE BRANCH MANUALLY!
  • Scroll down to "Publish Release" (not "Prepare") and click on it. Pull down the "Run workflow" button again. This time, you can edit the release tag for npm and set it to something other than latest if you want to make a prerelease (usually next).
  • Use the workflow from the release branch that was just made, and click on "Run workflow".
    • If you accidentally ran "Publish Release" on the main branch, it will fail harmlessly. Just do this step again.
  • Now just wait for the Publish Release action to complete.
    • It will upload prebuilds to S3.
    • It will publish all the builds with npm publish.
    • It will merge the release branch to main
    • It will create a tagged Release on github.
    • It will announce the release on Slack.
    • It will prepare the CHANGELOG.md for the next version.
  • If the "Publish Docs" action has not started automatically, click on that action and then click on "Run workflow".
    • Use the workflow from the main branch.
    • As the tag, enter the same version as was just released.
    • Click "Run workflow".
    • Once the workflow is done, verify that the new docs have been published by checking our API Reference page.

Troubleshooting

I accidentally published a release as latest when it should have been a tagged release

  • Reset the latest tag to point to the correct version (the last published version): npm dist-tag add realm@X.Y.Z latest, e.g. npm dist-tag add realm@10.11.0 latest
  • Set the tag to point to your version: npm dist-tag add realm@X.Y.Z-tag.n <tag_name>, e.g. npm dist-tag add realm@10.12.0-beta.0 beta

Note that npm caches versions for a short period of time so you may need to wait a minute for your changes to take effect.