Skip to content

Developer documentation

Jump to bottom
Stefan Dirix edited this page Jul 24, 2023 · 27 revisions

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 pnpm audit. If any fixes are available, apply them first via a PR
  2. pnpm run preparePublish
  3. Test in seed apps (for example via yalc)
  4. Publish via lerna. The single command is pnpm exec lerna publish --force-publish --git-remote [abc] [--dist-tag next] but it doesn't update peer dependencies correctly, therefore:
    • pnpm exec lerna version --no-push --force-publish --git-remote [abc]
    • Check versions of peer dependencies and manually update commit and tag if necessary (git tag <name> -f)
    • pnpm exec lerna publish from-git --git-remote [abc] [--dist-tag next]
    • git push [abc] [tag]

Post-Release Full

  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 🐤

Post-Release Prerelease

  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. Rebuild jsonforms2-website to update next version tag
  4. Do the twitter when it makes sense

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.

Clone this wiki locally