Heliotrope

Heliotrope is a front-end analytics library designed to make working with Segment IO simpler and more standardized.

Evergreen project NPM package

Quick Links

• API Documentation
• Local Testing and Development
  • Building the SDK
  • Using NPM Link
  • Using NPM Dev build packages
  • Using the dummy app
• Contributing
• Release
• License

API Documentation

Refer to the wiki to view SDK usage and API documentation.

Local Testing and Development

Before getting started, run npm install

Building the SDK

npm run build

• Babel is used to transpile the Typescript source code into Javascript code that can run in browsers supporting ES Modules
• Webpack takes the transpiled code and bundles it into a single, minified Javascript file in ./lib/heliotrope.min.js
• All of the contents of the build are outputted into the ./lib/ directory

Using NPM Link

To test local SDK changes you can use npm-link which essentially sets up symlinking such that another local project will symlink into this project.

1. In the heliotrope repo, run npm link
2. In the consuming repo that you want using the local SDK build, run npm link heliotrope
3. If you want to clean up the local npm linking in the consuming repo, run npm unlink heliotrope then npm install

Using NPM Dev build packages

If desired, you can publish a Dev build version of the SDK to NPM for local / integration testing needs. To do this, push up a git tag that matches the following pattern - dev-[a-zA-Z0-9-_]+ (dev-${1 or more of any combination of alphanumeric characters}). This will kick off a CI build that will publish the dev package. These dev packages have a special version comprised of several parts:

• The current release version in package.json
• The git tag name that triggered the task (must prefixed with `dev-`` string literal)
• The short git commit hash (first 7 characters of the git commit)

Example:

• The current release version = 5.1.1
• The git tag name = dev-cloudp-xyz
• The git commit hash = 0162ead1dd9e9ada34bf6952af4e5a592d1b02d6

Result:

• The published version = 5.1.1-dev-cloudp-xyz.0162ead
• To install = npm install @mongodb-js/[email protected]

Using the Dummy application

In order to run local checks to confirm Heliotrope is behaving as expected in the browser, we have included a local dummy app with which to run the SDK.

To see that Heliotrope methods are resulting in successful transmissions in your browser's network tab, run the following command then visit the localhost address displayed in your terminal:

npm run start-local
open http://localhost:1234

Contributing

Contributing to Heliotrope starts with a JIRA ticket. When creating tickets, the following field assignments are required:

• Project: Cloud Services (CLOUDP)
• Component: Heliotrope
• Fix Version: next-heliotrope-release

Open up a PR with the changes you'd like to make to the SDK with a summary of changes in the PR description (including the associated JIRA ticket). In the #heliotrope_analytics_sdk_frontend Slack channel, tag the @atlas-growth-platforms-eng for a review from the code owners and we will assign someone from the team to review. In addition, feel free to tag someone from your team to look at the PR as well.

Whenever making changes to Heliotrope (e.g. before merging a PR), add your change to the top of the CHANGELOG. Above the summary of the change, add the date and the text "Next Release".

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, ie #.#.# format. If it isn't, make a PR to make that update. In the PR, ensure that the Next Release section is replaced with the version number of the release
2. Get someone from the Atlas Growth Platforms team (@atlas-growth-platforms-eng on Slack) to create a new Github release tag off master with the tag value as the version and a description detailing the changes, with a reference and/or link to the related tickets and PRs. (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 release new prod version variant should appear in the the Evergreen project commits page. Monitor to see if the publish was successful.

License

Apache 2.0

See LICENSE