|
| 1 | +# New SDK Release Checklist |
| 2 | + |
| 3 | +This page serves as a checklist of what to do when releasing a new SDK for the first time. |
| 4 | + |
| 5 | +*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* |
| 6 | + |
| 7 | +## Release Preparation: |
| 8 | + |
| 9 | +- [ ] Make sure, the project is set up completely |
| 10 | + - [ ] The package exports the necessary modules |
| 11 | + - [ ] The package has a working unit testing environment |
| 12 | + - [ ] The package builds correctly (inspect `<package>/build` directory) |
| 13 | + |
| 14 | +- [ ] Make sure that the `README.md` content is up to date and contains at least: |
| 15 | + - [ ] The correct name + a brief description of the SDK |
| 16 | + - [ ] Badges pointing to the correct (yet not existing) NPM package *(this isn’t deadly necessary but nice to have)* |
| 17 | + - [ ] 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 |
| 18 | + - [ ] 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 |
| 19 | + - [ ] Extra information (e.g. how to upload sourcemaps) |
| 20 | + |
| 21 | +- [ ] Make sure that the `LICENSE` file exists and has the correct license (We default to the `MIT` license) |
| 22 | + - [ ] Also check, that the same license is mentioned in `package.json` |
| 23 | + |
| 24 | +- [ ] Make sure that the tarball (`yarn build:npm`) has all the necessary contents |
| 25 | + |
| 26 | + For basic SDKs, this means that the tarball has at least these files: |
| 27 | + |
| 28 | + - [ ] `cjs/<entrypoint>.js` |
| 29 | + - [ ] `esm/<entrypoint>.js` |
| 30 | + - [ ] `types/<entrypoint.d.ts>` |
| 31 | + - [ ] `package.json` |
| 32 | + - [ ] Entry points registered in this file match the file structure above |
| 33 | + - [ ] `LICENSE` |
| 34 | + - [ ] `README.md` |
| 35 | + - [ ] If your tarball should contain additional files outside `esm`, `cjs`, and `types` that are not listed above (e.g. like Gatsby or Remix), be sure to add a package-specific `prepack.ts` script. In this script, you can copy these additional files and make other adjustments.\ |
| 36 | + Check out the [Gatsby script](https://github.com/getsentry/sentry-javascript/blob/acd7fbb56ed1859ce48f06a76143075108631c25/packages/gatsby/scripts/prepack.ts#L1) as an example.\ |
| 37 | + 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. |
| 38 | + |
| 39 | +- [ ] Make sure `build.yml` CI script is correctly set up to cover tests for the new package |
| 40 | + - [ ] Ensure dependent packages are correctly set for “Determine changed packages” |
| 41 | + - [ ] Ensure unit tests run correctly |
| 42 | + |
| 43 | +## Cutting the Release |
| 44 | + |
| 45 | +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: |
| 46 | + |
| 47 | +**All of these steps should happen when you’re committed to releasing the SDK in the *next upcoming* release**. |
| 48 | + |
| 49 | +### Before the Release: |
| 50 | + |
| 51 | +- [ ] 1) If not yet done, be sure to remove the `private: true` property from your SDK’s `package.json` |
| 52 | +- [ ] 2) Make sure that the new SDK is **not added** in`[craft.yml](https://github.com/getsentry/sentry-javascript/blob/master/.craft.yml)` as a target for the **Sentry release registry**\ |
| 53 | +*Once this is added, craft will try to publish an entry in the next release which does not work and caused failed release runs in the past* |
| 54 | +- [ ] 3) Make sure the new SDK is not excluded from the github & npm targets in `.craft.yml` |
| 55 | +- [ ] 4) Cut a new release (as usual, via GH release action and Craft) |
| 56 | + |
| 57 | +### After the Release |
| 58 | + |
| 59 | +- [ ] 4) Check that the package was in fact published to NPM |
| 60 | +- [ ] 5) Add the new SDK to the [Sentry Release Registry](https://github.com/getsentry/sentry-release-registry) \ |
| 61 | + Instructions on how to do this can be found [here](https://github.com/getsentry/sentry-release-registry#adding-new-sdks) \ |
| 62 | + You have to fork this repo and PR the files from your fork to the main repo \ |
| 63 | + [Example PR](https://github.com/getsentry/sentry-release-registry/pull/80) from the Svelte SDK |
| 64 | + |
| 65 | +- [ ] 2) Add an entry to `[craft.yml](https://github.com/getsentry/sentry-javascript/blob/master/.craft.yml)` to add releases of your SDK to the Sentry release registry \ |
| 66 | + [Example PR](https://github.com/getsentry/sentry-javascript/pull/5547) from the Svelte SDK \ |
| 67 | + *Subsequent releases will now be added automatically to the registry* |
| 68 | + |
| 69 | + |
| 70 | +## Follow-up Tasks |
| 71 | + |
| 72 | +- [ ] Monitor GH for incoming bug reports/feature requests/praises/thank you messages/marriage proposals and potatoes |
| 73 | +- [ ] Feel good about yourself 😎 |
0 commit comments