Getting started with development on js-ceramic
This project requires Docker to be installed and actively running in your development environment for the unit tests to run.
First clone the repo:
$ git clone git@github.com:ceramicnetwork/js-ceramic.git
$ cd js-ceramic
This project uses npm and lerna to manage packages and dependencies. To install dependencies for all packages in this repo:
$ npm install
Then build all packages:
$ npm run build
When you change files, you will want to run lint to check your formatting
$ npm run lint
You can also have prettier automatically update non-conforming files
npx prettier --write "packages/**/src/**/*.ts"
You can run all tests at the top level,
$ npm test
If you only want to test a specific package just cd into the specific package folder and run the same command as above.
If you want to run the tests in recon mode, you must specify the ceramic-one path, the IPFS flavor as rust, and indicate that ceramic will run in recon mode on:
CERAMIC_ONE_PATH=<PATH> CERAMIC_RECON_MODE=true IPFS_FLAVOR=rust npm test
This repository contains many different JavaScript packages. The main reason for this is to keep things modular so that developers only need to pull in exactly the packages that they need.
| Package | Current Version | Description |
|---|---|---|
| @ceramicnetwork/3id-did-resolver |  |
DID resolver for 3ID DID method |
| @ceramicnetwork/blockchain-utils-linking |  |
Signature utilities for blockchain wallets |
| @ceramicnetwork/blockchain-utils-validation |  |
Signature verification utilities for blockchain wallets |
| @ceramicnetwork/cli |  |
Ceramic CLI and http daemon |
| @ceramicnetwork/common |  |
Ceramic types and utilities |
| @ceramicnetwork/core |  |
Ceramic protocol implementation |
| @ceramicnetwork/docid |  |
Encoding and decoding document identifiers |
| @ceramicnetwork/doctype-caip10-link |  |
Interface for CAIP-10 link doctype |
| @ceramicnetwork/doctype-caip10-link-handler |  |
Handler for CAIP-10 link doctype |
| @ceramicnetwork/doctype-tile |  |
Interface for tile doctype |
| @ceramicnetwork/doctype-tile-handler |  |
Handler for tile doctype |
| @ceramicnetwork/http-client |  |
HTTP client that can interact with a remote Ceramic daemon |
| @ceramicnetwork/pinning-aggregation |  |
Module that enables document pinning with multiple pinning backends |
| @ceramicnetwork/pinning-ipfs-backend |  |
Pinning backend for external ipfs node |
| @ceramicnetwork/pinning-powergate-backend |  |
Pinning backend for filecoin |
This repo uses lerna to make releases of all packages which have been changed. There are two types of releases that can be made, release candidates and regular releases. Before creating any releases, make sure you have an npm account (you can sign up at https://www.npmjs.com/), have signed into that account on the command line with npm adduser, and that the account has been added to the @ceramicnetwork org on npm.
After merging the changes you want to release into the relevant branch (main or release-candidate), you should build and verify the docker image before triggering the release to make sure nothing is broken.
First, install Dagger:
curl -L https://dl.dagger.io/dagger/install.sh
Then, in js-ceramic root:
dagger project init
dagger project update
dagger project update github.com/3box/pipeline-tools@v0.2.0
dagger do verify --log-format=plain -p cue.mod/pkg/github.com/3box/pipeline-tools/ci/plans/ceramic.cue
dagger do testJs --log-format=plain -p cue.mod/pkg/github.com/3box/pipeline-tools/ci/plans/ceramic.cue
dagger do testGo --log-format=plain -p cue.mod/pkg/github.com/3box/pipeline-tools/ci/plans/ceramic.cue
export GH_TOKEN=<your github token> # You need a valid github api token set to create the release on github
$ git checkout release-candidate
$ git merge origin develop # merge in recent changes from develop branch
$ npm install && npm run build # Make sure to build Ceramic and install current dependencies before releasing
$ npm adduser # login to npm account
$ npm run publish:release-candidate # create and publish the release
$ git checkout develop
$ git merge origin release-candidate # Merge the new release commit back into the develop branch
$ git push origin develop
The main step here is npm run publish:release-candidate, which creates a pre-release on NPM by bumping the minor version (e.g. 2.1.9 => 2.2.0-rc.0). It also creates a git commit with updated package versions as well as their corresponding git tags on github. Make sure to set the GH_TOKEN environment variable and log into npm before you run this command.
Afterwards, don't forget to make a post in the #releases channel of the Ceramic discord to notify the community about the new release candidate!
export GH_TOKEN=<your github token> # You need a valid github api token set to create the release on github
$ git checkout master
$ git merge origin release-candidate # merge in most recent release candidate
$ npm install && npm run build # Make sure to build Ceramic and install current dependencies before releasing
$ npm adduser # login to npm account
$ npm run publish:release # create and publish the release
$ git checkout release-candidate
$ git merge origin master # Merge the new release commit back into the release-candidate branch
$ git push origin release-candidate
$ git checkout develop
$ git merge origin master # Merge the new release commit back into the develop branch
$ git push origin develop
The main step here is npm run publish:release, which creates a full release on NPM by graduating the minor version (e.g. 2.2.0-rc.0 => 2.2.0). It also creates a git commit with updated package versions as well as their corresponding git tags on github. Make sure to set the GH_TOKEN environment variable and log into npm before you run this command.
Afterwards, don't forget to make a post in the #releases channel of the Ceramic discord to notify the community about the new release!
This option is necessary only when an urgent fix needs to be released to the community before we're ready to do a full release or RC. Note that whatever branch it's run against will be released as a full release, so it should generally be done from a recent fork of main. This branch MUST NOT be merged back into the main branch.
export GH_TOKEN=<your github token> # You need a valid github api token set to create the release on github
$ git checkout <hotfix branch>
$ npm install && npm run build # Make sure to build Ceramic and install current dependencies before releasing
$ npm adduser # login to npm account
$ npm run publish:hotfix # create and publish the release
The main step here is npm run publish:hotfix, which creates a full release on NPM by bumping the patch version (e.g. 2.1.9 => 2.1.10). It also creates a git commit with updated package versions as well as their corresponding git tags on github. Make sure to set the GH_TOKEN environment variable and log into npm before you run this command.
After the release, don't forget to make a post in the #releases channel of the Ceramic discord to notify the community about the new release!