This document describes the requirements and the process of creating releases of aepp-sdk to npmjs.com.

Prerequisites

A user wanting to release a new version needs to be a member of the @aeternity organization on npmjs.com. An existing member with write access needs to invite them in order to achieve this. In addition, the user needs to activate any means of 2-factor authentication because the aepp-sdk package is set up to only accept new versions if a second factor for authentication is in use.

As new releases should only happen from release branch merges to the master branch of the repository on GitHub followed by a signed tag push, the user also needs direct write access to on GitHub. Normally, this can be achieved by first adding them to the and then to the, which gives automatic write access.

Branching Out

As aepp-sdk follows the for development, the release process is modelled after that strategy accordingly, with a few additions.

Branch out from develop to a dedicated release branch denoting the target version number, e.g. release/v2.3.4.

Preparing a Pre-Release

If Testnet is not yet targeting the latest Node version, but you're "ready to release", you can do a pre-release for the latest version, tagging the release as @next on npmjs.

To do this, You can follow the steps listed below, while keeping the next portion in both CHANGELOG.md and package.json files.

Preparing a Release

On the release branch, remove the next portion of the version string in package.json.

Execute npm run release to automatically

• bump version number in package.json and package-lock.json (according to)

• output changes to

• commit package-lock.json and package.json and CHANGELOG.md

Next, git diff the release, branch a release/vX.X.X (where vX.X.X is your latest release) against master and validate that all changes are covered in the changelog. You can find more instructions on how to maintain a CHANGELOG here:

PR against master

Create a pull request against master and have it peer reviewed thoroughly. As all changes should've been reviewed before when they were merged to develop, emphasize on security-related changes and small changes pushed to develop separately.

Merging

Once the integration build has successfully completed (with or without additional fixes), merge (without squash) the branch into master. This allows master to be comprised of release commits exclusively, so every commit on master corresponds to exactly one released (or at least, tagged) version of aepp-sdk, respectively.

Build, Release and Tag

Update the local working copy to a local tracking branch of master and update. Optionally, wait for the CI build to finish and execute a lastnpm run test locally.

Important: Because npm publish will use the local files on disk for releasing, perform a full clean and build in order to release to npmjs.com!

1. Cleanup - run git clean -ffdx to completely wipe out your workspace of files not in the repository. This might wipe out files you still need, so consider a separate clone of the project!

2. Execute npm run prepublishOnly to generate Documentation for the API and the SDK codebase, optionally followed by npm pack and investigate the resulting tarball's contents. This tarball resembles what users will actually download from npmjs.com once the release is completed!

3. Execute npm publish

Important: If you are releasing a Pre-Release (AKA next), make sure to tag the release as next using the command npm publish --tag next.

At this point, the release should already be in npmjs.com. The final step is to also tag the release on GitHub and push the tag, which requires direct write access.

1. git tag vX.X.X

2. git push tag vX.X.X

Recommendation: Use signed tags using the -s option to increase community's trust in the project!

Merging Back into develop

At this point, it is important to synchronize develop with any changes that have happened after branching out to the release branch. Create a new branch called realign/vX.X.X from master (where vX.X.X is your latest release) and open a Pull Request towards develop and resolve conflicts, if needed.

This concludes the release process and the development cycle.

Principles

The Javascript SDK wraps the æternity API exposed byNode's Swagger file. It aims to abstract the API, while still providing low-level access to it's endpoints, when necessary.

It uses the following Javascript technologies and principles:

• JavaScript the Good Parts (because Crockford is always right)

• , using export and import

• using ES7 syntax, where applicable

• Statelessness wherever possible

• and the

• Loose coupling of modules to enable

• Convention over configuration

• "Easy things should be easy, and hard things should be possible." --

• Support for

  • module access, enabling tree-shaking

  • direct use in node scripts through bundling

  • direct use in browser <script> tags through bundling

Requirements

aepp-sdk is transpiled to EcmaScript 5 through , using and is expected to work in any sufficiently new version of or modern web browser.

Contributing

1. Clone the application

2. Make sure your editor/IDE can read and use the .editorconfig file

3. Start hacking (and don't forget to add for whatever you'll be building).

Documenting

Apart from documenting features and code, there is also documentation automatically generated using for documenting TS files and for documenting examples and code partials.

Building

aepp-sdk is built using npm. In order to build a production version, launch the build command.

Note: If you experience errors during the building, you might need to install build tools for your OS.

Windows: Windows Build Tools

Ubuntu / Debian: Build Essential

Mac

Download from AppStore, then run

Generate bundle report

Testing

To test, launch the test command. This will run 's tests locally.

This repository also includes a docker-compose file, to allow you to run your own æternity node locally. If you want to do so, from the root of the project:

1. Run docker-compose up node

2. Congrats! you're now running your own æternity node locally.

The WebPack compilation provides two different build artifacts in dist/, one for Node.js and one for browsers. When referencing aepp-sdk through any modern build tooling, it should pick the right one automatically through the entry points defined in package.json.

Installation / Linking

In order to add a local development version of aepp-sdk to a project, npm link can be used.

Releasing