@spmeesseman/app-publisher

v3.10.19

Published

a year ago

App Publisher

Downloads

0High
0Medium
0Low

spmeesseman

ci continuous integration ci tools ci utilities release automated release publish svn git npm github mantisbt

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Runs all scripts defined by the publishrc property buildCommand.

taskChangelog

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

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

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

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

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

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

Output the CI environment name to stdout.

taskCiEnvInfo

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

taskCiEnvSet

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

taskCommit

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

taskDeploy

Runs the deployment scripts defined in the .publishrc configuration.

taskDevTest

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

taskDistRelease

Perform a dist release.

taskEmail

Re-send the latest notification email.

taskGenerateCommands

Generate commands interface from readme file. Internal tool.

taskGithubRelease

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

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

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

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

Perform an 'NPM' release (publish).

taskNugetRelease

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

taskReleaseLevel

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

Reverts all local changes made by the publish run.

taskTag

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

Runs all scripts defined by the publishrc property testsCommand.

taskVersionCurrent

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

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

taskVersionInfo

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

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

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

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

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

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

Enables additional log output.

verbosex

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

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

App Publisher - Continuous Integration Tool

Table of Contents

Description

Requirements

Installation

Installation - NodeJS

Publishing Mode

Task Mode

Usage

Usage - Configuration File

How the Next Version is Determined

Commit Messages

VSCode Integration

CI Integration

Release Tokens

MantisBT Token

NPM Token

Jenkins Token

Command Line and Options

branch

buildCommand

buildPostCommand

buildPreCommand

bugs

changelogFile

changelogHdrFile

changelogLineLen

changelogSkip

commitMsgMap

commitPostCommand

commitPreCommand

config

configName

cProjectRcFile

deployCommand

deployPostCommand

disableTaskExplorer

distAddAllToVC

distDocPath

distDocPathSrc

distRelease

distReleasePath

distReleasePathSrc

distReleasePostCommand

distReleasePreCommand

dryRun

dryRunQuiet

emailHrefs

emailMode

emailPort

emailNotification

emailRecip

emailSender

emailServer

forceRelease

githubAssets

githubChglogEdit

githubRelease

githubReleasePostCommand

githubReleasePreCommand

githubUser

help

homePage

mantisbtApiToken

mantisbtAssets

mantisbtChglogEdit

mantisbtPlugin

mantisbtProject

mantisbtRelease

mantisbtReleasePostCommand

mantisbtReleasePreCommand

mantisbtUrl

noCi

npmPackDist