Skip to content

Latest commit

 

History

History
503 lines (453 loc) · 15.8 KB

README.md

File metadata and controls

503 lines (453 loc) · 15.8 KB
Raw

fluid-publish

A command line tool and node module that can be used to simplify the process of publishing a module to NPM. This is particularly useful for creating development releases, e.g. nightly or continuous integration releases.

By default this will create a release with version X.x.x-prerelease.yyyymmddThhmmssZ.shortHash where X.x.x is sourced from the version number in the package.json file, -prerelease is from the devTag option (also applied as a tag to the release), and the yyyymmddThhmmssZ.shortHash build identifier is generated based on the latest commit.

Installation

# global install
npm install fluid-publish -g

# local dev install
npm install fluid-publish --save-dev

Usage

Command Line API

Run these commands from the root directory of the module to be published.

# creates a dev release (global install)
fluid-publish

# creates a dev release (local install)
./node_modules/.bin/fluid-publish

--version

value: true (Boolean)

Returns the current version of the Fluid-Publish module itself. No publishing steps will occur when this flag is enabled.

# returns the version of fluid-publish
fluid-publish --version
# fluid-publish 2.0.0

--standard

value: true (Boolean)

Specifies that a standard release should be generated. This creates a release named after the version in the package.json file. It will not increase the version number. However, it will create a tag and publish this tag to the version control system.

# creates a standard release
fluid-publish --standard

--test

value: true (Boolean)

Specifies that a tarball should be created instead of publishing to NPM. This is useful to use a means of testing that the publish will happen correctly.

# creates a tarball
fluid-publish --test
fluid-publish --test --standard

# publishes to NPM
fluid-publish
fluid-publish --standard

--otp

value: (String)

Specifies the one-time password to use. This is required if the NPM account has two-factor authentication enabled.

# publishes to NPM and authenticating with a one-time password
fluid-publish --otp=12345

options

Optional key/value pairs, in the form key=value, to override the default configuration used across the publish script. The defaults can be found in publish.js's package.json file under the defaultOptions key.

NOTE: If only a key is provided, the value is assumed to be true

(See: Options, process.argv)

# publishes a dev build and applies the tag "nightly" to it
fluid-publish devTag="nightly"

JavaScript API

fluid.publish can also be accessed through standard JavaScript function calls in a node app.

dev

Publishes a development build. This creates a release named after the version, but with the build stamp appended to the end. By default this will create a release with version X.x.x-prerelease.yyyymmddThhmmssZ.shortHash where X.x.x is sourced from the version number in the package.json file, -prerelease is from the devTag option (also applied as a tag to the release), and the build identifier (yyyymmddThhmmssZ.shortHash) is generated based on the latest commit.

var publish = require("fluid-publish");
publish.dev();
arguments
  1. isTest {Boolean} - Indicates if this is a test run, if true a tarball will be generated instead of publishing to NPM.
  2. options {Object} - The defaults can be found in publish.js's package.json file under the defaultOptions key. (See: Options)

standard

Publishes a release build. This creates a release named after the version in the package.json file. By default it will not increase the version number, this must be done separately. However, it will create a tag and publish this tag to the version control system.

var publish = require("fluid-publish");
publish.standard();
arguments
  1. isTest {Boolean} - Indicates if this is a test run, if true a tarball will be generated instead of publishing to NPM.
  2. options {Object} - The defaults can be found in publish.js's package.json file under the defaultOptions key. (See: Options)

Options

Option Description Default
changesCmd The CLI to execute which determines if there are any uncommitted changes. It should return a string of changes, or nothing. "git status -s -uno"
checkRemoteCmd The CLI to execute which determines if the remote repository exists. This prevents trying to push a version control tag to a repo that doesn't exist. "git ls-remote --exit-code ${remote}"
rawTimestampCmd The CLI to execute which returns a git format timestamp for the most recent commit. "git show -s --format=%ct HEAD"
revisionCmd The CLI to execute which returns the most recent commit revision number/hash. "git rev-parse --verify --short HEAD"
branchCmd The CLI to execute which returns the name of the current branch. "git rev-parse --abbrev-ref HEAD"
otp A one-time password for NPM two-factor authentication.
otpFlag Applies the otp flag to the CLI to execute a publish command. This is needed if the NPM account uses two-factor authentication and will only be applied if the otp option is set.
  • ${command} will be substituted with the command being executed. Either publishCmd or publishDevCmd
  • ${otp} will be substituted with the one-time password provided.
"${command} --otp=${otp}"

NOTE: This is only required when two-factor authentication is enabled and will only be applied when a one-time password is provided.

packCmd The CLI to execute which constructs a tarball of the release artifact. "npm pack"
publishCmd The CLI to execute which publishes a release to NPM. "npm publish"
publishDevCmd The CLI to execute which publishes a development release to NPM. Uses the value specified by the `devTag` option. "npm publish --tag ${devTag}"
versionCmd The CLI to execute which sets the dev version to release under.
  • ${version} will be substituted with the generated dev build version.
"npm version --no-git-tag-version ${version}"

NOTE: This command will update the version in the package.json file, but will not commit the change.

cleanCmd The CLI to execute which cleans up any temporary changes to the package.json file.
  • ${package} will be substituted with the path to the executing modules package.json file.
"git checkout -- ${package}"
vcTagCmd The CLI to execute which creates the version control tag.
  • ${version} will be substituted with the version from the package.json file.
"git tag -a v${version} -m 'Tagging the ${version} release'"
pushVCTagCmd The CLI to execute which publishes the version control tag.
  • ${version} will be substituted with the version from the package.json file.
"git push upstream v${version}"
devVersion The string template for constructing a dev release version number.
  • ${version} will be substituted with the version in the package.json file.
  • ${timestamp} will be substituted with the generated ISO8601 timestamp based on the most recent commit.
  • ${revision} will be substituted with the revision/hash of the most recent commit.
"${version}.${timestamp}.${revision}"
devName An optional dev release name to be appended to the version. This will be separated by a "." (e.g. with "branchX" as the dev release name. 3.0.0.dev.20151015T131223Z.039d221.branchX). When a dev release is generated from a branch other than "master" or "main", the branch name will automatically be used as the dev release name, if devName is not supplied. ""
devTag The tag name to use for tagging dev releases. "dev"
remoteName The remote repository to push version control tag to. "upstream"
changesHint A hint for addressing uncommitted changes. "Address uncommitted changes: Commit \"git commit -a\", Stash \"git stash\" or Clean \"git reset --hard\"\n"
checkRemoteHint A hint for addressing an issue where the remote repository cannot be found. "Run \"git remote -v\" for a list of available remote repositories.\n"
publishHint A hint for addressing an issue where publishing a standard release to the registry fails. "Ensure that you have access to publish to the registry and that the current version does not already exist.\n"
publishDevHint A hint for addressing an issue where publishing a development (pre-release) to the registry fails. "Ensure that you have access to publish to the registry and that the current version does not already exist.\nIf the npm tag specified by --tag is recognizable as a valid semver version number, it will be rejected by npm. This is because version numbers and tags share a common namespace for npm packages.\n"
vcTagHint A hint for addressing an issue where applying a version control tag fails. "If the tag already exists, run \"git tag -d v${version}\" to remove the existing tag.\n"
pushVCTagHint A hint for addressing an issue where pushing a version control tag to a remote repository fails. "If the tag already exists, run \"git push ${remote} :refs/tags/v${version} to remove the existing tag. \n"

Publishing Itself

Publish can publish itself to NPM. This can be done using any of the usage methods described above, or via the NPM pub script defined in package.json. The script makes use of the command line interface provided to interact with publish.js. However, with NPM you'll need to provide a set of "--" to identify arguments to the script.

# publishes a dev release to NPM
npm run pub

# publishes a standard release to NPM
npm run pub -- --standard