diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bcb4efca..d0038342 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,15 @@ # Contributing -Thanks for stopping by! This document should cover most topics surrounding contributing to this repo. - -- [Contributing](#contributing) - - [Reporting issues](#reporting-issues) - - [Fixing issues](#fixing-issues) - - [Adding features](#adding-features) - - [System requirements](#system-requirements) - - [Testing](#testing) - - [CI](#ci) - - [Keeping dependencies in sync](#keeping-dependencies-in-sync) - - [Updating the CLI to install a compatible notifier version](#updating-the-cli-to-install-a-compatible-notifier-version) - - [Releases](#releases) - - [Prereleases](#prereleases) +This document should cover most topics surrounding contributing to this repo. + +* [Reporting issues](#reporting-issues) +* [Fixing issues](#fixing-issues) +* [Adding features](#adding-features) +* [Supporting new Expo SDK versions](#supporting-new-expo-sdk-versions) +* [System requirements](#system-requirements) +* [Testing](#testing) +* [CI](#ci) +* [Releasing](#releasing) ## Reporting issues Are you having trouble getting started? Please [contact us directly](mailto:support@bugsnag.com?subject=%5BGitHub%5D%20bugsnag-expo%20-%20having%20trouble%20getting%20started%20with%20Bugsnag) for assistance with integrating Bugsnag into your application. @@ -22,7 +19,7 @@ If you have spotted a problem with this module, feel free to open a [new issue]( * Has somebody else [already reported](https://github.com/bugsnag/bugsnag-expo/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen) your issue? Feel free to add additional context to or check-in on an existing issue that matches your own. * Is your issue caused by this module? Only things related to `@bugsnag/expo` (including `@bugsnag/plugin-*` plugins to support various frameworks) should be reported here. For anything else, please [contact us directly](mailto:support@bugsnag.com) and we'd be happy to help you out. -### Fixing issues +## Fixing issues If you've identified a fix to a new or existing issue, we welcome contributions! Here are some helpful suggestions on contributing that help us merge your PR quickly and smoothly: @@ -33,7 +30,7 @@ Here are some helpful suggestions on contributing that help us merge your PR qui * [Make a pull request](https://help.github.com/articles/using-pull-requests) * Ensure the automated checks pass (and if it fails, please try to address the cause) -### Adding features +## Adding features Unfortunately we’re unable to accept PRs that add features or refactor the library at this time. However, we’re very eager and welcome to hearing feedback about the library so please contact us directly to discuss your idea, or open a @@ -45,26 +42,15 @@ Here’s a bit about our process designing and building the Bugsnag libraries: * Our open source libraries span many languages and frameworks so we strive to ensure they are idiomatic on the given platform, but also consistent in terminology between platforms. That way the core concepts are familiar whether you adopt Bugsnag for one platform or many. * Finally, one of our goals is to ensure our libraries work reliably, even in crashy, multi-threaded environments. Oftentimes, this requires an intensive engineering design and code review process that adheres to our style and linting guidelines. +## Supporting new Expo SDK versions -## System requirements - -In order to develop on the project you’ll need to be on Mac/Linux٭. You’ll need: -- [node](https://nodejs.org) `v8+` (which includes [npm](https://www.npmjs.com/get-npm) 5+) -- [git](https://git-scm.com/) - -If you want to run the end-to-end tests locally you'll need [Docker](https://www.docker.com/products/docker-desktop) (including Docker Compose), and the [AWS CLI](https://aws.amazon.com/cli/). Note that you'll also need some BrowserStack and AWS credentials which are only available to Bugsnag employees. +### Updating the CLI to install a compatible notifier version -## Testing +When a new Expo SDK is released, a new matching `@bugsnag/expo` version needs to be published. For example, for SDK 48 there is a `@bugsnag/expo` v48. To mark the new SDK as supported, update the CLI's `LATEST_SUPPORTED_EXPO_SDK` in [`packages/expo-cli/lib/version-information.js`](./packages/expo-cli/lib/version-information.js). -A full guide to testing can be found in the [testing](./TESTING.md) document +For details on how to release a new version, please see the [release](./docs/RELEASING.md#new-major-release) document. -## CI - -CI runs on Buildkite. Tests are run automatically on any branch from within this repo. PRs from external repos do not run on the private test infrastructure. Once an external PR has been reviewed by a Bugsnag employee, a branch can be created within this repo in order to run on CI. - -⚠️ __Caution__: exercise due-diligence before creating a branch based on an external contribution – for example, be sure not to merge a bitcoin miner disguised as a bug fix! - -## Keeping dependencies in sync +### Keeping dependencies in sync The Expo notifier depends on some modules whose native code, if it exists, is bundled with Expo core. That means the version we depend on must match, otherwise we get conflicts and/or there are native/JS interface differences. @@ -88,93 +74,28 @@ https://github.com/expo/expo/blob/main/packages/expo/bundledNativeModules.json Additionally, `@bugsnag/expo` has a dependency on `promise` that must resolve to the same version used by `react-native` to ensure that we attach our unhandled rejection handler to the same instance of promise used by react-native. -## Updating the CLI to install a compatible notifier version - -When a new Expo SDK is released, a new matching `@bugsnag/expo` version needs to be published. For example, for SDK 44 there is a `@bugsnag/expo` v44. To mark the new SDK as supported, update the CLI's `LATEST_SUPPORTED_EXPO_SDK` in [`packages/expo-cli/lib/version-information.js`](./packages/expo-cli/lib/version-information.js) - -## Releases - -To start a release: - -- create and push a new branch (e.g. `v46`) from the latest previous branch (e.g. `v45` or `v45-next`) -- create a new next branch from which the release PR is to be made (e.g. `v46-next`) -- make the required dependency and CLI changes (see above) for the latest expo version -- regenerate the expo e2e test fixture using the expo create app cli -- update the version number and date in the changelog -- make a PR from your release branch (e.g. `v46-next`) to `v46` entitled `Release v46` -- get the release PR reviewed -- consider shipping a [prerelease](#prereleases) to aid testing the release - -Once the release PR has been approved: +### Creating a new example app -- merge the PR +This repository includes an example app for each supported version in the `/examples` directory. Please initialise a barebones app in this directory using the official expo tools, and remove versions no longer supported. We support the current version of expo and the last 2 major versions. -You are now ready to make the release. Releases are done using Docker and Docker compose. You do not need to have the release branch checked out on your local machine to make a release – the container pulls a fresh clone of the repo down from GitHub. Prerequisites: - -- You will need to clone the repository and have Docker running on your local machine. -- Ensure you are logged in to npm and that you have access to publish to the following on npm - - any packages in the `@bugsnag` namespace - - the `bugsnag-expo-cli` package -- Ensure your `.gitconfig` file in your home directory is configured to contain your name and email address -- Generate a [personal access token](https://github.com/settings/tokens/new) on GitHub and store it somewhere secure - -Build the release container: - -`docker-compose build release` - -Then make the release: - -``` -GITHUB_USER= \ -GITHUB_ACCESS_TOKEN= \ -RELEASE_BRANCH= \ -VERSION=patch \ - docker-compose run release -``` - -This process is interactive and will require you to confirm that you want to publish the changed packages. It will also prompt for 2FA. - -Browser bundles are automatically uploaded to the CDN if they have changed. - -Note: if a prerelease was made, to graduate it into a normal release you will want to use `patch` as the version. - -Finally: - -- create a release on GitHub https://github.com/bugsnag/bugsnag-expo/releases/new -- use the tag vX.Y.Z as the name of the release -- copy the release notes from `CHANGELOG.md` -- publish the release -- update and push `next`: - ``` - git checkout next - git merge master - git push - ``` +## System requirements -### Prereleases +In order to develop on the project you’ll need to be on Mac/Linux٭. You’ll need: +- [node](https://nodejs.org) `v8+` (which includes [npm](https://www.npmjs.com/get-npm) 5+) +- [git](https://git-scm.com/) -If you are starting a new prerelease, use one of the following values for the `VERSION` variable in the release command: +If you want to run the end-to-end tests locally you'll need [Docker](https://www.docker.com/products/docker-desktop) (including Docker Compose), and the [AWS CLI](https://aws.amazon.com/cli/). Note that you'll also need some BrowserStack and AWS credentials which are only available to Bugsnag employees. -``` -VERSION=[premajor | preminor | prepatch] -``` +## Testing -For subsequent iterations on that release, use: +A full guide to testing can be found in the [testing](./docs/TESTING.md) document -``` -VERSION=prerelease -``` +## CI -For example: +CI runs on Buildkite. Tests are run automatically on any branch from within this repo. PRs from external repos do not run on the private test infrastructure. Once an external PR has been reviewed by a Bugsnag employee, a branch can be created within this repo in order to run on CI. -``` -GITHUB_USER= \ -GITHUB_ACCESS_TOKEN= \ -RELEASE_BRANCH= \ -VERSION=preminor \ - docker-compose run release -``` +⚠️ __Caution__: exercise due-diligence before creating a branch based on an external contribution -Prereleases will automatically be published to npm with the dist tag `next`. +## Releasing -The dist tag ensures that prereleases are not installed by unsuspecting users who do not specify a version – npm automatically adds the `latest` tag to a published module unless one is specified. +A full guide to releases can be found in the [release](./docs/RELEASING.md) document diff --git a/docs/RELEASING.md b/docs/RELEASING.md new file mode 100644 index 00000000..cbefc4c9 --- /dev/null +++ b/docs/RELEASING.md @@ -0,0 +1,123 @@ +# Releasing + +## Create a release branch + +### Enhancements and bug fixes + +- decide on a new version number, following [semantic versioning](https://semver.org/) +- create a new release branch from `vX/next` with the new version number in the branch name i.e. `git checkout -b release/vX.Y.Z` +- update the version number and date in the changelog +- make a pull request from your release branch to `vX/main` entitled "Release vX.Y.Z" +- get the pull request reviewed – all code changes should have been reviewed already, this should be a review of the integration of all changes to be shipped and the changelog +- merge the PR + +⚠️ **Note**: Consider merging or cherry-picking the fix to other affected major version branches + +### New major release + +When a new Expo SDK is released, we should also publish a matching major version. + +- create and push a new **main** branch for the new supported Expo version (e.g. `v48/main`) from the latest current branch (e.g. `v47/main`), checking for unreleased changes in the equivalent `next` branch (e.g. `v47/next`) +- create a new **next** branch based on the new **main** branch (e.g. `v48/next`) +- create a feature branch from which the changes to support the new version are to be made (e.g. `PLAT-1234-support-v48`) +- make the required dependency and CLI changes for the latest Expo version (see [Keeping dependencies in sync](#keeping-dependencies-in-sync)) +- regenerate the e2e test fixture using the `create-expo-app` cli +- make a PR from the feature branch targeting the new **next** branch (e.g. `PLAT-1234-support-v48` to `v48/next`) +- create a release branch from **next** (e.g. `release/v48.0.0`) +- update the version number and release date in the changelog +- make a PR from your release branch targeting the new **main** branch (e.g. `release/v48.0.0` to `v48/main`) entitled `Release v48.0.0` +- get the release PR reviewed +- merge the PR + +The following digram demonstrates the flow of creating the required branches for new SDK release: + +```mermaid +graph TD; + v47/main-->v48/main; + v48/main-->v48/next; + v48/next-->PLAT-1234-support-v48; + PLAT-1234-support-v48-. PR .->v48/next; + v48/next-->release/v48; + release/v48-. PR .->v48/main; +``` + +## Publish the release + +You are now ready to make the release. Releases are done using Docker. You do not need to have the release branch checked out on your local machine to make a release – the container pulls a fresh clone of the repo down from GitHub. + +### Prerequisites + +- You will need to clone the repository and have Docker running on your local machine. +- Ensure you are logged in to npm and that you have access to publish to the following on npm + - any packages in the `@bugsnag` namespace + - the `bugsnag-expo-cli` package +- Ensure your `.gitconfig` file in your home directory is configured to contain your name and email address +- Generate a [personal access token](https://github.com/settings/tokens/new) on GitHub and store it somewhere secure + +### Building + +Before publishing your release, you must first build the release container: + +`docker-compose build release` + +### Publishing + +You may want to consider shipping a [prerelease](#prerelease) to aid testing the changes before publishing + +```sh +GITHUB_USER= \ +GITHUB_ACCESS_TOKEN= \ +RELEASE_BRANCH= \ +VERSION=[major | minor | patch] \ + docker-compose run release +``` + +This process is interactive and will require you to confirm that you want to publish the changed packages. It will also prompt for 2FA. + +**Note**: if a prerelease was made, to graduate it into a normal release you will need to use `patch` as the version. + +### Final Steps + +After publishing the release, the following steps must also be completed: + +- create a release on GitHub https://github.com/bugsnag/bugsnag-expo/releases/new +- use the tag vX.Y.Z as the name of the release +- copy the release notes from `CHANGELOG.md` +- publish the release +- update and push `vX/next`: + ```sh + git checkout v48/next + git merge v48/main + git push + ``` +- for new major versions: + - change the default branch on GitHub to the new `vX/next` branch + - update the `@bugsnag/js` pipeline on Buildkite so that it always triggers the latest 3 expo versions + +### Prereleases + +If you are starting a new prerelease, use one of the following values for the `VERSION` variable in the release command: + +``` +VERSION=[premajor | preminor | prepatch] +``` + +For subsequent iterations on that release, use: + +``` +VERSION=prerelease +``` + +For example: + +``` +GITHUB_USER= \ +GITHUB_ACCESS_TOKEN= \ +RELEASE_BRANCH= \ +VERSION=preminor \ + docker-compose run release +``` + +Prereleases will automatically be published to npm with the dist tag `next`. + +The dist tag ensures that prereleases are not installed by unsuspecting users who do not specify a version – npm automatically adds the `latest` tag to a published module unless one is specified. diff --git a/TESTING.md b/docs/TESTING.md similarity index 100% rename from TESTING.md rename to docs/TESTING.md