App Publisher - Continuous Integration Tool

App Publisher - Continuous Integration Tool

Description

This package provides a multi-release publishing mechanism similar to semantic-release using a more integrated approach, with support for Subversion as well as Git. The code base for this package was started from the semantic-release project, to give credit where it's due. This package originally focused on local environment releases (publish mode) and has since exposed a sort of CI tool interface (task mode) to be used for various things like retrieving the next version number from a CI script.

There are two modes to run app-publisher in:

Publishing Mode
Task Mode

Publishing Mode is similar to how semantic-release works, whereas Task Mode allows you to run individual pieces of the entire run, ideal for a multi-stage CI pipeline.

Requirements

Tested on Windows 10, "should" work on Linux/MacOS
NodeJS or Code Package

Installation

To install app-publisher globally for convenience, run the following command:

npm install -g @spmeesseman/app-publisher

To install locally per project, run the following command from the directory containing the projects package.json file:

npm install @spmeesseman/app-publisher

Installation - NodeJS

To run App-Publisher, nodejs and npm are required. These are by default installed with the Code Package installer.

To use App-Publisher without the Code Package environment, install NodeJS using the following steps:

Download NodeJS
Unzip the zipball to a directory on your hard drive, for example c:\nodejs
Add the unzipped directory's location to the SYSTEM PATH.

The download link for NodeJS above installs the version of NodeJS and NPM included with the Code Package install and is a simple zip based folder install. To download the latest version or a Windows installer, visit the NodeJS website.

With NodeJS and NPM installed, open a command line terminal and install App-Publisher globally using the command:

npm install -g @spmeesseman/app-publisher`

Note that to install the package with the above command, you must login to the registry first as described in the previous section.

To use App-Publisher, open a command line and navigate to the project directory containing the .publishrc.json file.

To see the list of available command line options, run the following command:

app-publisher -h

For a dry run, run the following command:

app-publisher --no-ci --dry-run

For a production release, run the following command:

app-publisher --no-ci

Publishing Mode

Publishing mode is similar to how semantic-release works. The entire set of publishing steps are ran according to the publishrc configuration.

The steps performed during an app-publisher run are:

Automatically determine next version from commit messages since last version. See the section on determining the next version here.
Auto-populate history text file and/or changelog markdown with commit messages since last version
Update all versioned files with new version
Run application specific build scripts
Build installer
Upload distribution files to network drive
Build and publish NPM package
Build and publish Nuget package
Run application specific deploy scripts
Check all modifications into VC
Tag with new version in VC
Upload a MantisBT or GitHub release including changelog and file assets
Send release email

Tip: A publishing mode dry run can be performed with the --dry-run option:

app-publisher --no-ci --dry-run

All steps are configured via the .publishrc configuration file

Task Mode

Task mode allows you to run pieces of the publishing run separately. This is ideal for a multi-stage or multi-step CI pipeline, where the run can be broken up between different stages of the CI run, customizable to accommodate most scenarios.

All tasks that run in task mode have to following command line switch format, where 'xyz' is the specific task:

--task-xyz

For example, to print the pending version's changelog to stdout so all pending changes since the last version can be examined, you can run:

app-publisher --task-changelog-print

To output it locally on the command line in your development environment, the --no-ci switch can be used:

app-publisher --no-ci --task-changelog-print

See Command Line and Options for details. You can also view details on command line arguments and switches by running app-publisher console help:

app-publisher --help

Tasks are influenced by the configuration set in the .publishrc configuration file.

Usage

For the latest help content, run app-publisher detailed help with the -h2 option.

App-Publisher can be run from the command line or in Visual Studio Code using the Task Explorer Extension. The Task Explorer extension will automatically detect .publishrc.* files in a project, and display the tasks within an app-publisher node.

Usage - Configuration File

Command line options and the .publishrc.* file can be used to define the configuration of a publishing or task run. To see all options and their descriptions, run app-publisher detailed help:

app-publisher -h
app-publisher --help

All options displayed with the exception of the --task-xyz switches are available .publishrc file properties, in camel cased form.

To configure app-publisher per project, create a .publishrc.json/js/yml file in the root project directory.

A sample .publishrc.json file can be taken from this project's root directory. This .publishrc file contains all available options.

Each option in the .publishrc file can be overridden on the command line. For example, if a publishrc configuration defines the sendEmail flag as"Y", a notification email will be sent at the end of the run... it can be overridden / turned off using the following command line argument and positional parameter:

app-publisher --send-email N

Environment variables can be used and expanded at runtime using the following syntax:

${ENVIRONMENT_VARIABLE_NAME}

How the Next Version is Determined

The next version is determined depending on the versioning system the application uses, and the set of commit messages made since the last version was released.

Two versioning system are supported:

Semver
Incremental

In the case where Semver is used to calculate the next version, the commit messages are examined to determine the next version level.

In the case of incremental versioning, version simply increment one number at a time, e.g. 100, 101, 102, etc.

Commit Messages

Commit message format is an integral part of the App Publisher release process.

See the standards here. See the GitHub standards here.

Commit messages should be made in the following format:

subject(scope): short_message

body

footer

The "subject" should be one of the following:

build
chore
ci
docs
feat
featmin
featmaj
fix
perf
project
refactor
style
visual

The "scope" can be anything specific to the commit change, for example:

docs(readme): update info on commit messages

It may also be committed, for example:

chore: update dependency for app-publisher to latest version

The subject "short_message" should be a short description of the change, preferably less than 160 characters.

The "body" should give a detailed explanation of the change.

The "footer" should give a detailed explanation of what the change fixes, or how it affects the application.

To reference issues from commit messages, use the "refs", "fixes", or "closes" tag anywhere in the commit message, for example:

fix(user management): the "add user" button doesnt work when selecting the option "clerk"

A typo was preventing the end user from being able to create a clerk type user.

Users should nw be able to create a clerk type user successfully.
Note that non-administrators do not have access to this functionality.
[fixes #142]

Including the [fixes #142] (or [closes #142]) tag in the footer will link the issue to the commit, auto-close the issue, remove any relevant tags from the issue, and add the "fixed" tag to the closed issue.

feat(job administration): add support for the "modify status" action

The action "Modify Status" in the Search Results tabs of Job Administration is now functional.

Note that the list of statuses that the jobs may be changed to will be reduced in the next release.
[refs #142]

Including the [refs #142] tag anywhere in the commit message will link issue #142 to the commit.

The commit messages will be used in the generation of the history and changelog files when running app-publisher.

References:

VSCode Integration

Integrates with the vscode-taskexplorer VSCode extension.

CI Integration

Prior to Version 3, App-Publisher was originally intended to be used as a release mechanism to be done from the local development environment, without the need for a CI system. Version 3 employs a complete pure NodeJS based overhaul, and has been adapted to be used as a tool in a CI environment to perform various tasks or release stages within a pipeline script. Some useful tasks include:

Retrieving the current version number
Retrieving the next version number (based on commit messages since the last release)
Setting the version in multiple files that contain the application version number (highly configurable).
Outputting a changelog
Performing an NPM release
Performing a GitHub release
Performing a MantisBT release (Releases Plugin required)
Handle pre-releases
Group scripts for various release stages and execute with a simple command.

Several other tasks are supported. See the Command Line and Options section for details

An example pipeline script written for Jenkins can be found in the Jenkinsfile at the root of the project.

Release Tokens

MantisBT Token

A MantisBT release requires the MANTISBT_API_TOKEN to be set in the system environment. To create a MantisBT token, perform the following steps:

Log into the MantisBT website
Go to User Preferences
Select the Tokens tab
Name the token RESTAPI
Click Create.
Copy the displayed token
Create a system environment variable named MANTISBT_API_TOKEN, where the token is it's value.

NPM Token

An NPM release may require the NPM_TOKEN to be set in the system environment. To create an NPM token, perform the following steps:

To create an npm user if you don't have one, run the following command and follow the prompts:

npm login --registry=https://npm.yourregistry.com --scope=@yourscope

Jenkins Token

In order to run the VSCode task Validate Jenkinsfile, the following environment variable must be set:

JENKINS_TOKEN

This token is the base64 encoded version of http basic auth using an API token, i.e. username:token

Command Line and Options

The following command line arguments and publishrc options are supported.

branch

Value Type	string
Value Default	trunk
Command Line Arg	-b \| --branch

The branch to use.

For SVN, this should include the path to the branches directory, e.g.:

branches/branch-name

SVN branch support can only work if there is a 'per project' branching folder / structure. It is assumed that the 'tags' folders is named by convention, i.e. '/tags'

buildCommand

Value Type	string \| string[]
Value Default
Command Line Arg	-bc \| --build-command

A script or list of scripts to run for the build stage.

buildPostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the build stage, after the build process is started.

buildPreCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the build stage, before the build process is started.

bugs

Value Type	string
Value Default
Command Line Arg	--bugs

Overrides the 'bugs' property of package.json when an NPM release is made, which is extracted for display on the project page of the NPM repository.

changelogFile

Value Type	string
Value Default	CHANGELOG.md
Command Line Arg	-cf \| --changelog-file

The location of this changelog file (markdown or text format), should be a path relative to the project's root.

changelogHdrFile

Value Type	string
Value Default
Command Line Arg	-chf \| --changelog-hdr-file

The location of this history header file, should be a path relative to the project's root.

changelogLineLen

Value Type	number
Value Default	80
Command Line Arg	-cll \| --changelog-line-len

The maximum line length to use when parsing commits to populate the changelog file.

changelogSkip

Value Type	boolean
Value Default	false
Command Line Arg	-clnt \| --changelog-skip

Ignore / skip the changelog file stage. Will not validate changelog file version.

commitMsgMap

Value Type	ICommitMessageMap[]
Value Default
Command Line Arg	n/a

A map of additional subject tags used in commits that will be used to increment the version and be included in the changelog, for example:

"commitMsgMap": {
    "internal": {
        "versionBump": "patch
        "formatText": "Internal Change
        "include": false,
        "iconCls": "fa-building
    }
}

commitPostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the commit stage, after the commit process is started.

commitPreCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the commit stage, before the commit process is started.

config

Value Type	boolean
Value Default	false
Command Line Arg	-c \| --config

Displays the configuration object and exits, for debugging. Note that the default publishrc file is '.publishrc.*'. A config file can be one of four different formats:

.publishrc.json
.publishrc.js
.publishrc.yaml
.publishrc.yml
package.json { publish: { ... } }

configName

Value Type	string
Value Default
Command Line Arg	-cn \| --config-name

Use config name. Note that the default publishrc file is '.publishrc.*'. A config name can dynamically modify the file used. For example, a config name of 'cst' will yield a search for the following config files:

.publishrc.cst.json
.publishrc.cst.js
.publishrc.cst.yaml
.publishrc.cst.yml
package.json { publish.cst: { ... } }

cProjectRcFile

Value Type	string
Value Default
Command Line Arg	-cprf \| --c-project-rc-file

The RC file name in a C Make project.

deployCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the deploy stage.

deployPostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the final release stage, before the final release process is started.

disableTaskExplorer

Value Type	flag
Value Default	N
Command Line Arg	n/a

Set to "Y" to disable the Task Explorer extension (if installed) from displaying app-publisher tasks.

distAddAllToVC

Value Type	flag
Value Default	N
Command Line Arg	-davc \| --dist-add-all-to-vc

Add the contents of the directory specified by the 'dist' property to version control, if not already.

Ignored if distRelease = "N".

distDocPath

Value Type	string
Value Default
Command Line Arg	n/a

The network path to use as the destination directory for a standard dist release's documentation directory. All PDF files found within the doc directory specified by the 'distDocPathSrc' property will be uploaded/copied to this directory.

Ignored if distRelease = "N" or distDocPathSrc is empty.

distDocPathSrc

Value Type	string
Value Default
Command Line Arg	-ddps \| --dist-doc-path-src

The local path to use as the source directory for a standard 'dist' release's documentation directory. All PDF files found within this directory are uploaded/copied to the directory specified by the 'distDocPath' property.

Ignored if distRelease = "N" or distDocPath is empty.

distRelease

Value Type	flag
Value Default	N
Command Line Arg	-dr \| --dist-release

Build a standard release to be uploaded to a network share.

distReleasePath

Value Type	string
Value Default
Command Line Arg	-drp \| --dist-release-path

The network path to use as the destination directory for a standard dist directory release. Will be renamed to 'distDestPath' in a future release.

The final directory created for the release will be:

distReleasePath/projectName/nextVersion"

Ignored if distRelease = "N".

distReleasePathSrc

Value Type	string
Value Default	install/dist
Command Line Arg	-drps \| --dist-release-path-src

The local path to use as the source directory for a standard 'dist' release. Will be renamed to 'distSrcPath' in a future release.

Ignored if distRelease = "N".

distReleasePostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the build stage, after building a standard dist release.

Ignored if distRelease = "N".

distReleasePreCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the build stage, before building a standard dist release.

Ignored if distRelease = "N".

dryRun

Value Type	boolean
Value Default	false
Command Line Arg	-dr \| --dry-run

Run in dry/test mode, all changes are reverted.

In dry-run mode, the following holds:

Installer is not released/published
Email notification will be sent only to $TESTEMAILRECIPIENT
Commit package/build file changes (svn) are not made
Version tag (svn) is not made

Some local files may be changed in test mode (i.e. updated version numbers in build and package files). These changes should be reverted to original state via SCM.

dryRunQuiet

Value Type	boolean
Value Default	false
Command Line Arg	-drq \| --dry-run-quiet

Same as 'dryRun', but minus stdout logging in the release emulations.

emailHrefs

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A link or list of links to insert into an email notification in the form 'link|name'.

emailMode

|Value Type |enum(std|ssl)| | :----------------- | :--------- | |Value Default |std| |Command Line Arg|n/a|

The delivery method to use when sending an email notification, possible values are:

ssl (Secure)
std (Standard / Non-Secure)

emailPort

Value Type	number
Value Default	25
Command Line Arg	n/a

The smtp server port to use when sending an email notification.

emailNotification

Value Type	flag
Value Default	N
Command Line Arg	-en \| --email-notification

Send a release email notification.

emailRecip

Value Type	string \| string[]
Value Default
Command Line Arg	-er \| --email-recip

The email address to use as the 'To' address when sending an email notification.

emailSender

Value Type	string
Value Default
Command Line Arg	-ef \| --email-sender

The email address to use as the 'From' address when sending an email notification.

emailServer

Value Type	string
Value Default
Command Line Arg	-es \| --email-server

The SMTP server to use when sending an email notification.

forceRelease

Value Type	boolean
Value Default	false
Command Line Arg	-fr \| --force-release

Force a release / publish run even if no relevant commits are found. The minor version will be bumped.

githubAssets

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A path to a file resource or list of file resource paths to upload as assets of the Github release.

Ignored if githubRelease = "N".

githubChglogEdit

Value Type	flag
Value Default	N
Command Line Arg	-gce \| --github-chglog-edit

Edit the manipulated changelog before creating the Github release.

Ignored if githubRelease = "N".

githubRelease

Value Type	flag
Value Default	N
Command Line Arg	-gr \| --github-release

Perform a Github release.

githubReleasePostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the release stage, after creating a Github release.

Ignored if githubRelease = "N".

githubReleasePreCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the release stage, before creating a Github release.

Ignored if githubRelease = "N".

githubUser

Value Type	string
Value Default
Command Line Arg	-gu \| --github-user

The Github username that owns the project the Github release will be made under. Used to construct the Github project path i.e. github.com/username.

Ignored if githubRelease = "N".

help

Value Type	boolean
Value Default	false
Command Line Arg	-h \| --help

Display console help.

homePage

Value Type	string
Value Default
Command Line Arg	--home-page

Overrides the homePage property of package.json when an NPM release is made, which is extracted for display on the project page of the NPM repository.

mantisbtApiToken

Value Type	string
Value Default
Command Line Arg	n/a

The MantisBT token or list of tokens to make a MantisBT release with. Represents the user that the release is made under on the 'Releases' page - Releases Plugin required.

mantisbtAssets

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A path to a file resource or list of file resource paths to upload as assets of the MantisBT release.

Ignored if mantisbtRelease = "N".

mantisbtChglogEdit

Value Type	flag
Value Default	N
Command Line Arg	-mce \| --mantisbt-chglog-edit

Edit the manipulated changelog before creating the MantisBT release.

Ignored if mantisbtRelease = "N".

mantisbtPlugin

Value Type	string
Value Default
Command Line Arg	-mp \| --mantisbt-plugin

Specifies the main project file for a MantisBT plugin project. The file extension must be '.php'"

mantisbtProject

Value Type	string
Value Default
Command Line Arg	-mpn \| --mantisbt-project

The MantisBT project name, if different than the main project name specified by projectName.

mantisbtRelease

Value Type	flag
Value Default	N
Command Line Arg	-mr \| --mantisbt-release

Perform a MantisBT release.

mantisbtReleasePostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the release stage, after creating a MantisBT release.

Ignored if mantisbtRelease = "N".

mantisbtReleasePreCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the release stage, before creating a MantisBT release.

Ignored if mantisbtRelease = "N".

mantisbtUrl

Value Type	string
Value Default
Command Line Arg	--mantisbt-url

The URL to use for creating a MantisBT release.

Ignored if mantisbtRelease = "N".

noCi

Value Type	boolean
Value Default	false
Command Line Arg	-nc \| --no-ci

Run in a local, non-CI environment.

npmPackDist

Value Type	flag
Value Default	N
Command Line Arg	-npd \| --npm-pack-dist

Copy the NPM package to the directory specified by distReleasePathSrc.

File is renamed from what is output by NPM, it is named as:

projectname.tgz

If the --config-name option is used, the file is named as:

projectname-configname.tgz

Ignored if npmRelease = "N".

npmRegistry

Value Type	string
Value Default	https://registry.npmjs.org
Command Line Arg	-nrg \| --npm-registry

The URL of the NPM registry to use for making an NPM release. This needs to be set if this is a privately hosted repository. Should be in the form:

https://npm.mydomain.com

Ignored if npmRelease = "N".

npmRelease

Value Type	flag
Value Default	N
Command Line Arg	-nr \| --npm-release

Build and make an NPM release.

npmReleasePostCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the release stage, after creating an NPM release.

Ignored if npmRelease = "N".

npmReleasePreCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A script or list of scripts to run for the release stage, before creating an NPM release.

Ignored if npmRelease = "N".

npmScope

Value Type	string
Value Default
Command Line Arg	-ns \| --npm-scope

The package scope to use for making an NPM release. Overrides the scope set in package.json. Ignored if npmRelease = "N".

nugetRelease

Value Type	flag
Value Default	N
Command Line Arg	-ngr \| --nuget-release

Build and make a Nuget release. Not supported as of v3.

promptVersion

Value Type	flag
Value Default	N
Command Line Arg	-pv \| --prompt-version

Prompt for version. The recommended version will be displayed at the prompt.

promptVersionDisable

Value Type	boolean
Value Default	false
Command Line Arg	-pvd \| --prompt-version-disable

Disables prompt for version in all cases. If a prompt is auto-ran due to specific application states, the next version will be auto-set to what is recommended by AP (the default value in the prompt). Overrides the promptVersion option if it is set.

projectFileDotNet

Value Type	string
Value Default
Command Line Arg	-pfdn \| --project-file-dot-net

Relative path to the .NET project version file (AssemblyInfo.cs). Any .NET assemblyinfo.cs files are attempted to be loaded and matched to a project, but in the case where it cannot, this property can be set."

projectFileExtJs

Value Type	string
Value Default
Command Line Arg	-pfej \| --project-file-ext-js

Relative path to the ExtJs project version file (app.json). Any ExtJs app.json files are attempted to be loaded and matched to a project, but in the case where it cannot, this property can be set."

projectFileNpm

Value Type	string
Value Default
Command Line Arg	-pfn \| --project-file-npm

Relative path to the NPM project version file (package.json). Any NPM package.json files are attempted to be loaded and matched to a project, but in the case where it cannot, this property can be set.

projectName

Value Type	string
Value Default
Command Line Arg	-pn \| --project-name

Name of the project. This must match throughout the build files and the VCS project name.

projectVersion

Value Type	string
Value Default
Command Line Arg	n/a

Utility field for tracking version if no other mechanism is available.

repo

Value Type	string
Value Default
Command Line Arg	-rp \| --repo

The repository URL. In the form:

https://svn.mydomain.com/path/to/repo/projectname/trunk
https://github.com/username/projectname

repoType

|Value Type |enum(git|svn)| | :----------------- | :--------- | |Value Default |git| |Command Line Arg|-rpt | --repo-type|

The repository type. It should be one of the following:

republish

Value Type	boolean
Value Default	false
Command Line Arg	-r \| --republish

Re-publish the current/latest release. Can be used for multi-publish configurations to bypass local version file validation.

skipChangelogEdits

Value Type	flag
Value Default	N
Command Line Arg	-sce \| --skip-changelog-edits

Skip manual editing of the changelog file(s). Note the changelog used for a release will be that of which is output by the internal commit parser.

skipCommit

Value Type	flag
Value Default	N
Command Line Arg	-sc \| --skip-commit

Skip committing changes to version control when the final release stage is finished (commit stage).

skipTag

Value Type	string
Value Default	N
Command Line Arg	-st \| --skip-tag

Skip tagging version in version control when the final release stage is finished (commit stage).

skipTags

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A tag name or list of tag names that will be ignored when evaluating remote tags for versioning. CAn be used when a tag has been accidentally created, or deleted.

skipVersionEdits

Value Type	flag
Value Default	N
Command Line Arg	-sve \| --skip-version-edits

Skip all version edits in version files.

taskBuild

Value Type	boolean
Value Default	false
Command Line Arg	-tb \| --task-build

Runs all scripts defined by the publishrc property buildCommand.

taskChangelog

Value Type	boolean
Value Default	false
Command Line Arg	-tc \| --task-changelog

Export the next release's current changelog and view using the editor specified in the .publishrc file. Note that this opens the actual versioned changelog/history file.

taskChangelogFile

Value Type	string
Value Default
Command Line Arg	-tcf \| --task-changelog-file

Export the next release's current changelog to the specified file, can be a relative or an absolute path. Ignored if the option '--task-changelog-view' is used.

Usage:

app-publisher -tcf install/dist/history.txt
app-publisher -tcf build/doc/changelog/changelog.md
app-publisher -tcf c:\\projects\\changelogs\\projectname\\cl.md
app-publisher --task-changelog-file build/tmp/version_notes.txt

taskChangelogHdrPrint

Value Type	boolean
Value Default	false
Command Line Arg	-tchp \| --task-changelog-hdr-print

Read the changelog's header from disk and output to stdout.

taskChangelogHtmlFile

Value Type	string
Value Default
Command Line Arg	-tchf \| --task-changelog-html-file

Export the next release's pending changelog in HTML release format to the specified file, can be a relative or an absolute path. Ignored if the option '--task-changelog-view' is used.

Usage:

app-publisher --task-changelog-html-file install/tmp/version_notes.html

taskChangelogHtmlPrint

Value Type	boolean
Value Default	false
Command Line Arg	-tchtmp \| --task-changelog-html-print

Export the next release's pending changelog in HTML release format and output to stdout. Constructed from commits made since the last release.

taskChangelogHtmlPrintVersion

Value Type	string
Value Default
Command Line Arg	-tchpv \| --task-changelog-html-print-version

Export the specified version's changelog in HTML release format and output to stdout. Reads directly from the changelog file.

taskChangelogHtmlView

Value Type	boolean
Value Default	false
Command Line Arg	-tchv \| --task-changelog-html-view

Export the next release's pending changelog in HTML release format and view using the editor specified in the .publishrc file. The created file is a copy stored in a temporary directory specified by the OS.

taskChangelogPrint

Value Type	boolean
Value Default	false
Command Line Arg	-tcp \| --task-changelog-print

Export the next release's pending changelog and output to stdout. Constructed from commits made since the last release.

taskChangelogPrintVersion

Value Type	string
Value Default
Command Line Arg	-tcpv \| --task-changelog-print-version

Export the specified version's changelog and output to stdout. Reads directly from the changelog file.

Usage:

app-publisher --no-ci -tcpv 1.2.4
app-publisher --task-changelog-print-version 3.0.1

taskChangelogHdrPrintVersion

Value Type	string
Value Default
Command Line Arg	-tchpv \| --task-changelog-hdr-print-version

Read the changelog's header from disk and output to stdout, using the specified version number.

taskChangelogView

Value Type	boolean
Value Default	false
Command Line Arg	-tcv \| --task-changelog-view

Export the next release's current changelog and view using the editor specified in the .publishrc file. The created file is a copy stored in a temporary directory specified by the OS.

taskChangelogViewVersion

Value Type	string
Value Default
Command Line Arg	-tcvv \| --task-changelog-view-version

Export the specified release's current changelog and view using the editor specified in the .publishrc file. The created file is a copy stored in a temporary directory specified by the OS.

taskCiEnv

Value Type	boolean
Value Default	false
Command Line Arg	-tce \| --task-ci-env

Output the CI environment name to stdout.

taskCiEnvInfo

Value Type	boolean
Value Default	false
Command Line Arg	-tcei \| --task-ci-env-info

Finds CI related build information, and outputs the info to stdout using a concatenated string in the form 'current|next|changelogpath'.

taskCiEnvSet

Value Type	boolean
Value Default	false
Command Line Arg	-tces \| --task-ci-env-set

Finds CI related build information, and outputs the info to the file 'ap.env' in the root workspace directory.

taskCommit

Value Type	boolean
Value Default	false
Command Line Arg	-tcm \| --task-commit

Commits the changes made when using the --task-version-update option, using the 'chore: vX.X.X' format for the commit message.

taskDeploy

Value Type	boolean
Value Default	false
Command Line Arg	-td \| --task-deploy

Runs the deployment scripts defined in the .publishrc configuration.

taskDevTest

Value Type	boolean
Value Default	false
Command Line Arg	-tdt \| --task-dev-test

Run temporary tests in the local dev environment. Note that this does nothing when ran in a production build.

taskDistRelease

Value Type	boolean
Value Default	false
Command Line Arg	-tdr \| --task-dist-release

Perform a dist release.

taskEmail

Value Type	boolean
Value Default	false
Command Line Arg	-te \| --task-email

Re-send the latest notification email.

taskGenerateCommands

Value Type	boolean
Value Default	false
Command Line Arg	-tgc \| --task-generate-commands

Generate commands interface from readme file. Internal tool.

taskGithubRelease

Value Type	boolean
Value Default	false
Command Line Arg	-tgr \| --task-github-release

Perform a 'Github' release. The changelog produced for the Github release will be created from the most recent entry of the changelog/history file.

taskMantisbtRelease

Value Type	boolean
Value Default	false
Command Line Arg	-tmr \| --task-mantisbt-release

Perform a 'Mantis' release. The changelog produced for the Mantis release will be created from the most recent entry of the changelog/history file.

taskNpmJsonRestore

Value Type	boolean
Value Default	false
Command Line Arg	-tnjr \| --task-npm-json-restore

Restores changes made to the package.json file as a result of using the --task-npm-json-update task. Properties include:

bugs, homepage, repo, repoType

Note that this task should in most cases always be ran following the use of the --task-npm-json-update task.

taskNpmJsonUpdate

Value Type	boolean
Value Default	false
Command Line Arg	-tnju \| --task-npm-json-update

Updates package.json with .publishrc defined properties. Properties include:

bugs, homepage, repo, repoType

Can be used for publishing to multiple npm repositories. Note that this task should in most cases always be followed up with a --task-npm-json-restore task.

taskNpmRelease

Value Type	boolean
Value Default	false
Command Line Arg	-tnr \| --task-npm-release

Perform an 'NPM' release (publish).

taskNugetRelease

Value Type	boolean
Value Default	false
Command Line Arg	-tngr \| --task-nuget-release

Perform a 'Nuget' release (not implemented yet).

taskReleaseLevel

Value Type	boolean
Value Default	false
Command Line Arg	-trl \| --task-release-level

Gets the release level for the next release and outputs it to stdout. Release level will be one of 'none', 'patch', 'minor', or 'major'.

taskRevert

Value Type	boolean
Value Default	false
Command Line Arg	-tr \| --task-revert

Reverts all local changes made by the publish run.

taskTag

Value Type	boolean
Value Default	false
Command Line Arg	-tt \| --task-tag

Creates a tag using the 'vX.X.X' format for the tag name. The 'taskVersionUpdate' and 'taskVersionUpdateCommit' tasks should always precede this task.

taskTagVersion

Value Type	string
Value Default
Command Line Arg	-ttv \| --task-tag-version

Creates a tag using the specified positional parameter as the tag name. The 'taskVersionUpdate' and 'taskVersionUpdateCommit' tasks should always precede this task.

Usage:

app-publisher --task-tag-version 2.0.0

taskTests

Value Type	boolean
Value Default	false
Command Line Arg	-tb \| --task-tests

Runs all scripts defined by the publishrc property testsCommand.

taskVersionCurrent

Value Type	boolean
Value Default	false
Command Line Arg	-tvc \| --task-version-current

Finds the current/latest version released and outputs that version string to stdout.

Ignored if the --task-version-info switch is used.

taskVersionInfo

Value Type	boolean
Value Default	false
Command Line Arg	-tvi \| --task-version-info

Finds the current/latest and next version released, and outputs the info to stdout using a concatenated string in the form:

current_version|next_version|release_level

Note that this switch overrides both the --task-version-current and the --task-version-current switches.

taskVersionNext

Value Type	boolean
Value Default	false
Command Line Arg	-tvn \| --task-version-next

Calculates the next version to be released based on versioned files and commit messages. and outputs that version string to stdout.

Ignored if the --task-version-info switch is used.

taskVersionPreReleaseId

Value Type	string
Value Default
Command Line Arg	-tvprid \| --task-version-pre-release-id

Gets the identifier denoting a pre-release from a version string. For example, the version string 2.20.11-alpha.3 has a pre-release identifier of 'alpha'.

Usage:

app-publisher --task-version-pre-release-id 2.0.1-alpha.1
app-publisher --task-version-pre-release-id 2.0.1-beta.3

taskVersionUpdate

Value Type	boolean
Value Default	false
Command Line Arg	-tvu \| --task-version-update

Update version numbers either semantically or incrementally. Versioned files are by default AssemblyInfo.cs, package.json, and app.json. Additional versioned files are specified in the .publishrc file using the 'versionFiles' and cProjectRcFile' properties.

testEmailRecip

Value Type	string \| string[]
Value Default
Command Line Arg	-ter \| --task-email-recip

The email address to use as the 'To' address when sending an email notification while running in dry run mode."

tests

Value Type	boolean
Value Default	false
Command Line Arg	-t \| --tests

Runs tests (development use only).

testsCommand

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

Command(s) to run for tests stage, immediately following build stage. The only difference between using this command and the buildPostCommand is that this command will fail the publish run if the script returns a non-zero exit code, whereas buildPostCommand will contine with the publish run regardless of the script's exit code.

textEditor

Value Type	string
Value Default	notepad.exe
Command Line Arg	-tedr \| --text-editor

The editor program to use when opening version files for manual editing."

vcFiles

Value Type	string[]
Value Default
Command Line Arg	n/a

A list of files that should be checked into version control in the commit phase. These would include files generated/moved/modified by any of the hook scripts that are to be included in the version commit/tag"

vcRevert

Value Type	flag
Value Default	Y
Command Line Arg	-vr \| --vc-revert

Reverts all file modifications made if a publish fails, or, after a dry run is completed. Uses version control.

vcRevertFiles

Value Type	string[]
Value Default
Command Line Arg	n/a

Additional files to be reverted if a publish run fails, or, after a dry run completes. Uses version control.

Ignored if vcRevert = "N".

vcStdOut

Value Type	boolean
Value Default	false
Command Line Arg	-vso \| --vc-std-out

true, boolean false, Outputs stdout from the vc process (git or svn) and pipes it to the current runs stdout. Use for debugging version control issues.

vcTagLookup

Value Type	number
Value Default	50
Command Line Arg	-vtl \| --vc-tag-lookup

The maximum number of tags to look up when caculating the next version and/or pre-release version numbers.

vcTagPrefix

Value Type	string
Value Default
Command Line Arg	-vtp \| --vc-tag-prefix

Tag prefix for the version tag. Labels the created tag in the form prefix-vX.X.X.

vcWebPath

Value Type	string
Value Default
Command Line Arg	-vwp \| --vc-web-path

Web path to the version control repository e.g. the project's home page on GitHub, or for a Subversion project the project root in a web viewer such as WebSVN. Primarily used for dynamically creating links in the changelogs and/or email notifications.

verbose

Value Type	boolean
Value Default	false
Command Line Arg	-vbs \| --verbose

Enables additional log output.

verbosex

Value Type	boolean
Value Default	false
Command Line Arg	-vbsx \| --verbosex

Enables additional log output, including stringified objects. Pronounced 'ver-bose ecks' ;)

version

Value Type	boolean
Value Default	false
Command Line Arg	-v \| --version

Display the current app-publisher version.

versionFiles

Value Type	IVersionFile[]
Value Default
Command Line Arg	n/a

A file path or list of file paths to perform version string replacement in. A source/target pair can lso be specified using the 'setFiles' property.

Example:

 "versionFiles": [{
     "path": "..\\..\\install\\GEMS2_64bit.nsi",
     "regex": "!define +BUILD_LEVEL +VERSION",
     "regexVersion": "[0-9a-zA-Z\\.\\-]{5,}",
     "regexWrite": "!define BUILD_LEVEL      "VERSION"
 },
 {
     "path": "node_modules\\@pja\\extjs-pkg-server\\package.json",
     "setFiles": [{
         "path": "app.json",
         "regex": "svrVersion" \*: \*"VERSION",
         "regexVersion": "[0-9a-zA-Z\\.\\-]{5,}",
         "regexWrite": "svrVersion": "VERSION"
     },
     {
         "path": "..\\svr\\assemblyinfo.cs",
         "regex": "AssemblyVersion *\\(VERSION",
         "regexVersion": "[0-9]+\\.[0-9]+\\.[0-9]+",
         "regexWrite": "AssemblyVersion\\(VERSION"
     }]
 }]

The regex must contain the text 'VERSION' which translates to the capturing group used to obtain the actual version number, and it must be the first group if more than one capturing groups exist in the regex. The 'regexVersion' property is the regex that will match the version, and defaults to the regex [0-9a-zA-Z\\.\\-]{5,} if not specified. This property is optional and defaults to system:semver.

versionForceCurrent

Value Type	boolean
Value Default	false
Command Line Arg	-vfc \| --version-force-current

Force current version, for use with post release tasks such as re-sending an email notification or performing a GitHub release if for whatever reason it failed on the publish run.

Usage:

app-publisher --task-email --version-force-current

versionForceNext

Value Type	string
Value Default
Command Line Arg	-vfn \| --version-force-next

A version number to use as the 'next version'. Version calculation will not be performed other than for reading in the current version from the local version files, skipping an SCM step.

Usage:

app-publisher --version-force-next 300
app-publisher --version-force-next 2.0.0

versionFilesEditAlways

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A file path or list of file paths to always perform version string replacement in, regardless of whether the skipVersionEdits flag is set.

versionFilesScrollDown

Value Type	string \| string[]
Value Default
Command Line Arg	n/a

A file path or list of file paths where scroll-down is perfoemed when opened for editing.

versionPreReleaseId

Value Type	string
Value Default
Command Line Arg	-vpri \| --version-pre-release-id

An identifier denoting a pre-release can to be appended to the next version number to produce the final version string, e.g. 'alpha' produces the final version string of x.y.z-alpha.

See versionPreReleaseId for details on how pre-release versions are incremented.

Usage:

app-publisher --version-pre-release-id alpha
app-publisher --version-pre-release-id beta
app-publisher --version-pre-release-id pre

versionPreReleaseLimit

Value Type	boolean
Value Default	false
Command Line Arg	-vprl \| --version-pre-release-limit

If set, allows only one level increment away from the last production build during a pre-release development stage when determing the next version from a set of commit messages. For example, if the last production release is 2.0.2, the pre-release versions will only be allowed to increment to 3.0.0-pre.X, 2.1.0-pre.X, or 2.0.3-pre.X, where pre is the pre-release tag, such as alpha or beta and X is the pre-release build number.

The default behavior is to allow normal incrementing for all pre-releases regardless of the last production version. This means that is the last production version is 2.0.2, the next production version could be 2.5.4, or 3.1.1, depending on the pre-releases made between each production release.

Note that the versionPreReleaseId must also be specified when using this option. Usage:

app-publisher --version-pre-release-id alpha --version-pre-release-limit

versionSystem

Specify the versioning system to be used if it cannot be determined automatically:

semver Ex. 1.0.0, 1.0.1, 1.0.2
incremental Ex. 100, 101, 102"

versionText

Value Type	string
Value Default	Version
Command Line Arg	-vt \| --version-text

The text tag to use in the history file for preceding the version number. It should be one of the following:

Version
Build
Release

writeLog

Value Type	flag
Value Default	N
Command Line Arg	-wr \| --write-log

In addition to stdout, writes a log to LOCALAPPDATA/app-publisher/log