The version-tools package provides APIs and a CLI to parse and transform version numbers and ranges that are used by the Fluid Framework.
Fluid Framework packages sometimes use version schemes that diverge from standard semantic versioning. By default, a new package should use standard semantic versioning. However, there are also two other versioning schemes: internal and virtualPatch.
The Fluid internal version scheme consists of two semver "triplets" of major/minor/patch. The first triplet is called the public version, and is stored in the typical semver positions in the version string.
The second triplet is called the internal version, and is found at the end of the pre-release section of the version string.
Fluid internal version strings always include the string internal in the first position of the pre-release
section.
In the following example, the public version is a.b.c, while the internal version is x.y.z.
a.b.c-internal.x.y.z
-
isInternalVersionScheme-- Returns true if a string represents an internal version number. -
isInternalVersionRange-- Returns true if a string represents an internal version range. -
toInternalScheme-- Converts a standard semver version string to the internal version scheme. -
fromInternalScheme-- Converts an internal version scheme string into two standard semvers -- one for the public version and one for the internal version. -
bumpInternalVersion-- Given an internal version and a bump type, returns the bumped version. -
getVersionRange-- Given an internal version and a constraint type, returns a dependency version range that enforces the constraint.
The Fluid virtualPatch version scheme is only used for pre-1.0 packages. Versions are of the form:
0.major.minorpatch
The minor version and patch version are combined by multiplying the minor version by 1000 and then adding the patch
version. For example, for the standard semver 1.2.3, the virtualPatch version scheme would yield 0.1.2003.
Minor versions always start at 1 instead of 0. That is, the first release of a major version 3 would be 0.3.1000.
-
isVirtualPatch-- Returns true if a string represents an internal version number.
-
detectVersionScheme-- Given a version or a range string, determines what version scheme the string is using. -
incRange-- Increments a range by the bump type (major, minor, or patch), maintaining the existing constraint.
version-tools provides a command-line interface (fluv) when installed directly. However, the commands listed here are
also available in the Fluid build and release tool (flub). This is accomplished using
oclif's plugin system.
$ npm install -g @fluid-tools/version-tools
$ fluv COMMAND
running command...
$ fluv (--version|-V)
@fluid-tools/version-tools/1.0.0
$ fluv --help [COMMAND]
USAGE
$ fluv COMMAND
...Display autocomplete installation instructions.
USAGE
$ fluv autocomplete [SHELL] [-r]
ARGUMENTS
SHELL (zsh|bash|powershell) Shell type
FLAGS
-r, --refresh-cache Refresh cache (ignores displaying instructions)
DESCRIPTION
Display autocomplete installation instructions.
EXAMPLES
$ fluv autocomplete
$ fluv autocomplete bash
$ fluv autocomplete zsh
$ fluv autocomplete powershell
$ fluv autocomplete --refresh-cache
See code: @oclif/plugin-autocomplete
Display help for fluv.
USAGE
$ fluv help [COMMAND...] [-n]
ARGUMENTS
COMMAND... Command to show help for.
FLAGS
-n, --nested-commands Include all nested commands in the output.
DESCRIPTION
Display help for fluv.
See code: @oclif/plugin-help
Convert version strings between regular semver and the Fluid internal version scheme.
USAGE
$ fluv version VERSION [--json] [-t major|minor|patch|current] [--publicVersion <value>]
ARGUMENTS
VERSION The version to convert.
FLAGS
-t, --type=<option> bump type
<options: major|minor|patch|current>
--publicVersion=<value> [default: 2.0.0] The public version to use in the Fluid internal version.
GLOBAL FLAGS
--json Format output as json.
DESCRIPTION
Convert version strings between regular semver and the Fluid internal version scheme.
EXAMPLES
The version can be a Fluid internal version.
$ fluv version 2.0.0-internal.1.0.0 --type minor
The version can also be a semver with a bump type.
$ fluv version 1.0.0 --type minor
If needed, you can provide a public version to override the default.
$ fluv version 1.0.0 --type patch --publicVersion 3.1.0
You can use ^ and ~ as a shorthand.
$ fluv version ^1.0.0
You can use the 'current' bump type to calculate ranges without bumping the version.
$ fluv version 2.0.0-internal.1.0.0 --type current
See code: src/commands/version.ts
Find the latest version from a list of version strings, accounting for the Fluid internal version scheme.
USAGE
$ fluv version latest -r <value> [--json] [--prerelease]
FLAGS
-r, --versions=<value>... (required) The versions to evaluate. The argument can be passed multiple times to provide
multiple versions, or a space-delimited list of versions can be provided using a single
argument.
--prerelease Include prerelease versions. By default, prerelease versions are excluded.
GLOBAL FLAGS
--json Format output as json.
DESCRIPTION
Find the latest version from a list of version strings, accounting for the Fluid internal version scheme.
EXAMPLES
You can use the --versions (-r) flag multiple times.
$ fluv version latest -r 2.0.0 -r 2.0.0-internal.1.0.0 -r 1.0.0 -r 0.56.1000
You can omit the repeated --versions (-r) flag and pass a space-delimited list instead.
$ fluv version latest -r 2.0.0 2.0.0-internal.1.0.0 1.0.0 0.56.1000
See code: src/commands/version/latest.ts
This package outputs its build files to lib/ instead of dist/ like most of our other packages. The reason is that
oclif uses the lib folder by convention, and there are oclif bugs that can be avoided by putting stuff in lib. See the
PR here for an example: https://github.com/microsoft/FluidFramework/pull/12155
Due to https://github.com/oclif/core/issues/630, the build:manifest node script uses an experimental flag. This can be
removed once we have upgraded to Node 16 in the repo.
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.