jscutlery/semver

Document differences with `nx release` and migration options

samuelfernandez opened this issue · 1 comments

It would be very nice to have documentation on how this plugin resembles and differentiates from nx release. Also, document how to migrate the configuration to the new integrated solution using Nx CLI.

edbzn commented

Main differences:

  • Nx release is still in Alpha version where semver has been tested on many projects over 3 years
  • Nx release keep all package versions in sync by default whereas semver by default treats projects independently
  • Nx release needs config for the first release
  • Nx release runs globally on the workspace where semver runs individually on every project (in independent mode)
  • Nx release creates one single commit whereas semver creates multiple ones (in independent mode)
  • Nx release has 3 separate commands (version, changelog, publish) where semver has one single configurable command (update: nx release can run with one single command)
  • Nx release can be configured globally in nx.json where semver is statically configured in each project.json or dynamically using the Plugin API (inference)

Nx release features not supported by semver:

  • Release groups
  • Updating any projects that depend on them to use the new version
  • Programmatic APIs
  • Configurable version resolver (semver is tag-based)
  • Optional tagging

Semver features not supported by Nx release:

  • Running a series of executors when a new release is made (--postTargets)
  • Supporting all conventional changelog presets and making them configurable
  • Skipping some commit types to trigger new releases (--skipCommitTypes)
  • Supporting GitLab release
  • Producing a patch bump when dependencies change (--trackDeps)

Migrating from Semver to Nx release:

Some work is made to bring migration scripts to semver to let users explore the new Nx Release. However, these scripts will have limitations like migrating the CI setup, supporting extremely customized versioning processes, etc...

To be completed...