@spmeesseman/app-publisher

    3.10.3 • Public • Published

    App Publisher - Continuous Integration Tool

    perry-johnson app-category app-lang app-publisher

    authors MantisBT issues open MantisBT issues closed MantisBT version current

    app-publisher-cmdline-banner

    Table of Contents

    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:

    1. Publishing Mode
    2. 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 @perryjohnson/app-publisher
    

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

    npm install @perryjohnson/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:

    1. Download NodeJS
    2. Unzip the zipball to a directory on your hard drive, for example c:\nodejs
    3. 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 @perryjohnson/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:

    1. Semver
    2. 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 omitted, 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:

    1. Retrieving the current version number
    2. Retrieving the next version number (based on commit messages since the last release)
    3. Setting the version in multiple files that contain the application version number (highly configurable).
    4. Outputting a changelog
    5. Performing an NPM release
    6. Performing a GitHub release
    7. Performing a MantisBT release (Releases Plugin required)
    8. Handle pre-releases
    9. 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:

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

    NPM Token

    An NPM release requires the NPM_TOKEN to be set in the system environment. To create a PJ 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 adduser --registry=npm.development.pjats.com --scope=@spmeesseman
    

    After a period of time, the session token created with this command will expire. When the token expires, run the login command:

    npm login --registry=npm.development.pjats.com --scope=@spmeesseman
    

    For more details, see the Internal NPM Registry section of the Perry Johnson Developer Notes document.

    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.

    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:

    1. Installer is not released/published
    2. Email notification will be sent only to $TESTEMAILRECIPIENT
    3. Commit package/build file changes (svn) are not made
    4. 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.

    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:

    1. git
    2. svn

    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."

    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

    |Value Type |enum(auto|semver|incremental)| | :----------------- | :--------- | |Value Default |auto| |Command Line Arg|-vs | --version-system|

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

    1. semver Ex. 1.0.0, 1.0.1, 1.0.2
    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:

    1. Version
    2. Build
    3. 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

    Install

    npm i @spmeesseman/app-publisher

    DownloadsWeekly Downloads

    6

    Version

    3.10.3

    License

    MIT

    Unpacked Size

    568 kB

    Total Files

    15

    Last publish

    Collaborators

    • spmeesseman