Circular Wave SDK

The SDK is not really an SDK in the traditional sense. It is simply a library that contains shared code, which is depended on by all of Circular Wave's backend services.

Branching Model

The SDK's main branch is the master branch. Small PRs are typically merged directly to master. Larger changes may use a feature branch. There is no dev branch for the SDK.

TypeScript

Version 6 of the SDK onwards use TypeScript. Unlike the microservices (which use esbuild), the SDK uses the official TypeScript compiler (tsc) as it needs to generate .d.ts files for consumption by the microservices. There are two commands provided for compiling the TypeScript to JavaScript:

  • npm run build which run the TypeScript compiler once
  • npm run watch which runs the TypeScript compiler in watch mode to continously compile when files change.

When developing the SDK, it is recommended to run the TypeScript compiler in watch mode using npm run watch (TypeScript files will also be automatically compiled as part of the prepublish script as a failsafe to avoid accidentally publishing the SDK with out of date compiled files).

The compiled JavaScript files are generated into the dist directory and are not committed to git. However, they are included in the published NPM module. The .npmignore file is important the enabling this to work properly, as without it NPM will default to exluding anything in .gitignore from the published module (see: .npmignore files docs).

Local Development

To test out changes to the SDK locally, you can use yarn link to make locally running microservices pick up the local version of the SDK rather than using the version from NPM. To do this:

  • Run npm link in the SDK directory
  • Run npm link @circularwave/marketplace-ms-sdk in each microservice (that you want to use the local SDK version)

Sometimes the linking can get messed up, in which case you can run the following to relink:

  • Run npm unlink && npm link in the SDK directory
  • Run npm unlink @circularwave/marketplace-ms-sdk && npm link @circularwave/marketplace-ms-sdk in each microservice

Sometimes running yarn in the microservices can mess up the installed node_modules of the SDK, in which case you should re-run yarn in the SDK to fix the problem.

Remember to have the TypeScript compiler running while developing the SDK (see TypeScript section above).

Versioning & Changelog

The SDK does not follow semver. Breaking changes may happen in minor versions (they are indicated with BREAKING in the changelog), and major version changes are used to indicate significant changes in the SDK. Typically, code that uses the SDK is checked and updated so as to not be effected by breaking changes before the change is made (or at least before the SDK version is updated in that microservice.)

A changelog is maintain in CHANGELOG.md in the SDK repository.

Obtaining an NPM Token

To obtains an NPM token for publishing and installing the SDK:

  • Go to https://www.npmjs.com/
  • Click the "Sign In" link
  • Sign in using the credentials from Bitwarden (username: ashleyrudland - the name of Circular Wave's ex-CTO)
  • Enter the TOTP code, which is also available from Bitwarden (see: Using Generated TOTP Code)
  • Once signed in, click the profile picture menu in the top-right and select "Access Tokens"
  • Click "Generate New Token"
  • Give the new token a name (e.g. [Aug 2022] Nico's Laptop)
  • Select "Publish" permissions, and click "Generate Token" to create it
  • Copy the generated token and export it as an environment variable in your .zshrc/.bashrc (add the line export NPM_TOKEN=token-content-goes-here to your .zshrc/.bashrc)

Publishing Changes

To publish changes, the following steps should be carried out:

  • Ensure that you have an NPM token with publishing permissions set as the NPM_TOKEN environment variable (see instructions below on obtaining a token)
  • Ensure CHANGELOG is up to date with changes since the last released version
  • Update the version number in package.json
  • Run npm publish
  • Commit and push changes

Updating microservices to new SDK versions

Once the new SDK version has been published, you can update the microservices to use the new version. This can either be done manually, or using a helper script stored in the devenv repository.

Option 1: Manually

In each microservice (replacing 1.2.3 with the actual version number that you want to update to):

  • Run yarn upgrade @circularwave/marketplace-ms-sdk@1.2.3
  • Commit changes. Conventionally we use the commit message Upgraded SDK to v1.2.3

Option 2: Using the script

First ensure that you have no uncommited changes in any of the microservice repositories.

Then, in the devenv root directory:

  • Run VERSION=1.2.3 node ./upgrade-sdk-version.js

This will automatically update the dev branches of each microservice to the latest version. You may wish to inspect to source of this script, as it is quite simple and it sometimes fails for various reasons (for example if you forget to commit any uncommitted changes, or if there is a network error), in which case it is useful to understand what it going on under the hood in order get everything properly updated.