Developer documentation

Developer documenation

Handling of package-lock.json and versioning in JSONForms

• Use the guidlines outlined in First time setup to setup JSONForms.

• By default, the package-lock.json should not be modified

• If you need to update a specific version of a package, do so in an explicit commit and add the package.json and package-lock.json files. Pay attention to package hoisting warnings

  NOTE: There should be no package-lock.json files in any of the packages subfolders. If that is the case, it means that lerna was not able to bootstrap the packages cleanly, likely because of existing hoisting warnings.

• From time to time, we might have commits that only update packages, e.g. when using npm audit

Creating a new release

Release

1. Run npm audit. If any fixes are available, apply them first via a PR
2. npm login with 'eclipsesource'
3. npm run preparePublish
4. Test publishing by either:
   • Publishing to a private npm registry (see section 'Testing a local release')
   • by using a custom version number, e.g. using a -rc suffix
5. Publish via lerna publish
6. Update own peerDependencies to next version

Post-Release

1. Check https://www.npmjs.com/search?q=%40jsonforms for the new release
2. Check https://github.com/eclipsesource/jsonforms/releases for the new release
3. Update jsonforms-react-seed
4. Update make-it-happen-react and make-it-happen-angular, if necessary
5. Update jsonforms2-website
   • Generate and copy API docs
6. Create change log by going through all issues in the milestone
7. Publish release on github
8. Close milestone
9. Do the twitter 🐤

Testing a local release

You can test the entire release process locally on your machine. This is useful for when packages are published initially. To do so, follow these instructions:

1. First install verdaccio which is a local npm registry that can be started on your machine and follow the instructions to set-up your registry as well as a user.
2. Clone a copy of the JSONForms repo, which we'll refer to as $JSONFORMS_CLONE from here on
3. Navigate to $JSONFORMS_CLONE and execute git config receive.denyCurrentBranch ignore. This is necessary for pushing the tag created by lerna
4. Within the repo from which you want to release, execute git remote add $REMOTE_NAME $JSONFORMS_CLONE, where $REMOTE_NAME is an arbitrary name (except origin maybe ;)
5. Follow the release process by executing npm run preparePublish
6. Execute lerna publish --git-remote $REMOTE_NAME (TODO: I also needed to add --force-publish=*, otherwise not all packages were picked up, why?)
7. Check the published packages at http://localhost:4873 and the created tag within $JSONFORMS_CLONE
8. Consume and test the published packages if they work as intended
9. If so, revert the repo from where you published to HEAD^
10. Delete $JSONFORMS_CLONE
11. Revert your npm registry settings

Npm Tags

Npm tags are string identifiers which can be attached to versions of (released) packages. They can be changed at any time using the npm dist-tag command, e.g. npm dist-tag add <pkg>@<version> <tag> and npm dist-tag rm <pkg> <tag>. Each tag can only be attached to a single version at any point of time. There is no set limit to the amount of tags used.

Users can refer to package versions via their tag, for example npm install @jsonforms/core@next installs the version of @jsonforms/core which is currently tagged with next if it exists.

The only magic tag is latest. If a user installs a package without a version specification, e.g. npm install @jsonforms/core, npm will deliver the package which is tagged with latest. This tag is automatically attached to a newly published version by default. The automatically attached tag can be changed by specifying the --dist-tag <tag> parameter when publishing via lerna or using the --tag <tag> parameter when publishing via npm.

Many packages use the next tag as a convention to tag (possibly API breaking) releases within their development stream. Other potentially useful tags could be alpha, beta, prerelease, dev, stable etc.