npm package: @mongodb-js/mdb-experiment-js
Description: JS SDK to allocate and check experiment data at MongoDB.
Author: MongoDB Atlas Growth
Latest version: 1.9.0

# @mongodb-js/mdb-experiment-js-sdk

[Evergreen project](https://evergreen.mongodb.com/waterfall/mdb-experiment-js-sdk)
[NPM package](https://www.npmjs.com/package/@mongodb-js/mdb-experiment-js)

## Purpose

This SDK is meant to be used with clients who have access to the MMS backend endpoints and are authenticated. If you do not have access and are not authenticated, this code will not work.

## Functionality

Please run `npm run docs` to view the TypeDocs for this repo.

Also see [the wiki]() for experimentation process and best practices.

### Local Development with MMS

For local development of the SDK codebase, it's helpful to link it to your local MMS code so that changes in the SDK source code can be easily QA'ed in your local MMS server. The steps to do so are as follows:

1. In your SDK folder, where package.json is, run `npm link`
2. Also run `npm link [path to your MMS folder or $MMS_HOME if you have that alias]/client/node_modules/react`. This ensures only 1 version of React is running in the local application.
3. In MMS/client, where package.json is, run `npm link @mongodb-js/mdb-experiment-js` to symlink to your local mdb-experiment-js sdk folder.
4. Run `npm run prepare` in your SDK folder whenever you want to generate new `dist` files, which MMS should automatically pick up.

In general this should be a one-time setup, although if you notice your local development isn't working, check for the presence of these symlinks in your node_modules folders and if needed, run these steps again.

If you want to mimic "real" MMS, aka use the specified version of the SDK package in MMS's package.json, you can run `npm unlink @mongodb-js/mdb-experiment-js` to remove the symlink to your local folder and then run `npm install` to get the SDK package from npm. If you want to relink the 2, just run `npm link @mongodb-js/mdb-experiment-js` again.

## Documentation

The code will have [JSDoc](https://jsdoc.app/) annotations and use [TypeDoc](https://typedoc.org/guides/overview/) to generate documentation.

### Types

Each type/interface should have a description in a comment block.
Each type property should have a description and an example as appropriate.
There's no need to annotate `@type` information as JSDoc can figure that out on its own.

### Functions

Each function should have at least:

```markdown
- @description - including intended usage as a section in here.
- @params - include IF there are params.
- @return - include IF there is a returned value. Do not need to include the return type as Typescript takes care of documenting that for TypeDocs and Intellisense. Just write a descriptive comment on what the function returns.
- @throws - include IF the function can throw an error.
- @example
```

## Release

Releases are triggered when a new Git tag is created. Here are the steps to publish a new package to npm:

1. Make sure the package.json `version` field in the `main` branch is the package version you want to publish, following [semantic versioning](https://docs.npmjs.com/about-semantic-versioning), ie #.#.# format. If it isn't, make a PR to make that update.
2. Get a Growth team lead or `@JohnMealy23` or `@diiiefiend` to create a new Github release tag off `main` with the tag value as the version and a description detailing the changes, with a reference and/or link to the related tickets. (If you would like to be added as permissioned to publish, also speak to the above parties--it requires being added to the Evergreen Project config list.)
3. A new "publish" variant should appear in the [the Evergreen project waterfall page](https://evergreen.mongodb.com/waterfall/mdb-experiment-js-sdk). Monitor to see if the publish was successful.

## License

Apache 2.0

See [LICENSE](./LICENSE)