Provide API for plugins to handle releases

[RobertDiebels]

Request

First of all, thank you for the tools you've written. They're a major help to us.

As for my issue, I would like to request that NX CLI has its release mechanism decoupled from the Javascript plugin entirely.
As it stand the NX CLI is tightly coupled with the @nx/js plugin and attempts to replace that plugin are complicated though not impossible.

The decoupling should result in a well-defined API that plugins can implement/extend enabling them to handle releases for the projects that they govern.

Right now the @nx/js handles versioning, changelogs and releasing in a non consistent manner.

Current method(s)

Below I list how a plugin may override the release process of projects in a NX workspace.

Versioning

This can be overridden by providing a generator option in the nx.json under the release options.

This generator option is undocumented.

Once the generator option is provided, a plugin will have to use the project-marker files (or configFiles as per NX documentation) and (depending on the generator options) other data as both a source of the version and a sink for the new version and associated changelogs.

I put a large amount of effort into reading and understanding the way the @nx/js:release-version generator does this. To put it mildly, the code associated with that generator is very hard to read, and I refactored the majority of the code in a (unpublished) plugin I wrote.

Publishing

This can be overridden by providing a nx-release-publish target for a project.

This too is undocumented

For this a plugin can simply provide the target and add a executor that reads from the project-marker files.

Inconsistencies

From the above it should be easy to see that customizing both versioning and publishing do not have a consistent API. Versioning requires you to supplant the release-version generator, whereas publishing requires you to have a fixed target name and corresponding target configuration.

Utilities

Versioning

NX does not provide any utility functions to handle versioning or publishing in a plugin. This increases the difficulty of integrating tools into NX which do not publish artifacts currently supported by NX.

Proposal

As a first step, NX should extract a well-defined internal API for the @nx/js:release-version generator code. Which can eventually be made public and documented. Added benefit to this is increasing the readability of the current code.

As a second step, NX should create a clearly defined orchestration method for the release process and make it as easy as possible for a plugin to provide version-sources/-resolvers and -sinks. This means breaking the currently undocumented public API in some places and ensuring that both versioning and publishing utilize the same method of extending the release process.

In turn the above should result in an extension mechanism for releasing that is easy to grasp and does not depend on hardcoded identifiers within the release process.

I have already rewritten a large chunk of the @nx/js:release-version generator for a plugin I wrote, hence I'm most willing and capable of creating a PR for the first step.

Regarding the second step, I would love to work on that however, knowingly breaking the public API of a product is something I would preferably leave to its developers, or at the very least do in cooperation with them. Since I've yet to get feedback on this proposal I'll leave to the NX maintainers to gauge who should do what, if the proposal is even accepted to begin with.