New SDK Release Checklist

This page serves as a checklist of what to do when releasing a new SDK for the first time.

This checklist was written while working on the @sentry/svelte Alpha 1 release. Some parts in this checklist might differ slightly for other SDKs depending on how they are structured and how they work

Release Preparation:

• Make sure, the project is set up completely

  • The package exports the necessary modules
  • The package has a working unit testing environment
  • The package builds correctly (inspect <package>/build directory)

• Make sure that the README.md content is up to date and contains at least:

  • The correct name + a brief description of the SDK
  • Badges pointing to the correct (yet not existing) NPM package (this isn’t deadly necessary but nice to have)
  • If the SDK is not yet stable, a clear message indicating that it is in alpha/beta state and that breaking changes can still occur
  • A brief description how to set up and configure the SDK. If you already have docs, add a link to the docs, otherwise link to the “parent” SDK docs (e.g. @sentry/browser) if applicable
  • Extra information (e.g. how to upload sourcemaps)

• Make sure that the LICENSE file exists and has the correct license (We default to the MIT license)

  • Also check, that the same license is mentioned in package.json

• Make sure that the tarball (yarn build:tarball) has all the necessary contents

  For basic SDKs, this means that the tarball has at least these files - you can configure what is included in the tarball via the files field in package.json:

  • build/cjs/<entrypoint>.js (or build/npm/cjs/<entrypoint>.js)
  • build/esm/<entrypoint>.js (or build/npm/esm/<entrypoint>.js)
  • build/types/<entrypoint.d.ts> (or build/npm/types/<entrypoint>.js)
  • package.json
    • Entry points registered in this file match the file structure above
  • LICENSE
  • README.md
  • Any additional files that should be part of the tarball
  • It’s recommended to build and pack a tarball and then yarn add path/to/tarball.tar.gz it to your test app(s) to ensure that it has all the correct files.

• Make sure build.yml CI script is correctly set up to cover tests for the new package

  • Ensure unit tests run correctly
  • If it is a browser SDK, add it to BROWSER_TEST_PACKAGES in scripts/ci-unit-tests.ts

• Make sure the file paths in the "Upload Artifacts" job in build.yml include your new artifacts.

  • This is especially important, if you're adding new CDN bundles!
  • Tarballs (*.tgz archives) should work OOTB

• Make sure it is added to the Verdaccio config for the E2E tests

• If the package you're adding is a dependency of fullstack framework (e.g. Remix or NextJS) SDKs, make sure that your package is added to the integration test apps' "resolutions" field in their package.jsons.

• Add the new package to the "root" README inside the repository.

• Add the new package to the GitHub Issue bug template.

• Create label inside the GitHub repo named "Package: foobar".

Cutting the Release

When you’re ready to make the first release, there are a couple of steps that need to be performed in the correct order. Note that you can prepare the PRs at any time but the merging oder is important:

All of these steps should happen when you’re committed to releasing the SDK in the next upcoming release.

Before the Release:

• 1. If not yet done, be sure to remove the private: true property from your SDK’s package.json. Additionally, ensure that "publishConfig": {"access": "public"} is set.
• 2. Add an npm target in craft.yml for the new package. Make sure to insert it in the right place, after all the Sentry dependencies of your package but before packages that depend on your new package (if applicable).
  ymlCopy

  - name: npm
    id: '@sentry/[yourPackage]'
    includeNames: /^sentry-[yourPackage]-\d.*\.tgz$/
  

• 3. Add a registry target in craft.yml for the new package. For new packages, Craft will automatically create the required directory structure and initial manifest in the Sentry Release Registry (Craft Docs).
  ymlCopy

  name: 'Sentry [Package] SDK'
  sdkName: 'sentry.javascript.[package]'
  packageUrl: 'https://www.npmjs.com/package/@sentry/[package]'
  mainDocsUrl: 'https://docs.sentry.io/platforms/javascript/guides/[package]/'
  onlyIfPresent: /^sentry-[package]-\d.*\.tgz$/
  

• 4. Cut a new release (as usual, see Publishing Release)

After the Release

• 1. Check that the package was in fact published to NPM
• 2. Check that the SDK is added to the Sentry Release Registry npm packages and SDK symlinks
• 3. In case the package is missing anywhere, add the missing content. Instructions on how to do this can be found here Example PR from the Svelte SDK.

Follow-up Tasks

• Monitor GH for incoming bug reports/feature requests/praises/thank you messages/marriage proposals and potatoes
• Feel good about yourself 😎