@madk/release NPM

A Little Release Tool

This is a NodeJS-based release tool that helps create a release on Conventional Commit-conventions. It can be run both locally and in CI environments. The idea is to provide a wrapper around solid tools, that provides the basic functionality of releaseing an application/website/library with flexibility, but with sane defaults.

This tool is very early in development. Use at your own risk.
Only tested in a few contexts
Lacking testing across node version
Needs extended test cases for criticial functionality
Missing configuration features

A release is created by: 1. Test (default: npm test) 2. Bump (Uses semver/conventional commit tooling) to figure out the next version 3. Generate changelog using conventional-changelog 4. Build (optional, default: npm run build) 4. Custom updates through updaters (optional, see below for more info) 5. Publish (optional, default: npm publish)

You can also:

Publish through SFTP
Bump to specific versions (don't decide automatically)
Control output through CLI arguments or environment variables/configuration
Skip steps

Usage

CLI

Install it globally, npm i -g @madk/release, or locally, npm i @madk/release, and run it through npm-scripts.

To create a simple release, just run release. There are multiple CLI-options available (see below), and even more configuration abilities if you use a configuration file.

More usage instructions:

Usage: release [options] [folder]

Create a release.
This runs tests, bumps and commits a version, creates a tag, generates a changelog by default.

Arguments:
  folder                        Absolute path of git repository. Defaults to the current directory. (default: "C:\\Users\\madka\\Projects\\madk-release")

Options:
  --bump <string>               Override what we are bump the version to. Could be any valid semver/conventional changelog type of release.
  --build [command]             Build the package before publish. (preset: "npm run build", env: RELEASE_BUILD)
  --publish [npm|sftp|command]  How we are publishing Can be a preset (npm/sftp) or a custom terminal-command. (preset: "npm", env: RELEASE_PUBLISH)
  --config <configPath>         Override what configuration file to use. The path should be a file relative to the <folder>. (env: RELEASE_CONFIG)
  --test [command]              Skip running tests before doing anything. (env: RELEASE_TEST)
  --skip-test                   Skip running tests before doing anything.
  -r, --dry-run                 Do not actually commit or do anything. (default: false)
  -s, --silent                  Silence all log output. This has precedence if set (default: false)
  -v, --verbose                 Output extra information. (default: false)
  -d, --debug                   Output extra debug information. (default: false)
  --skip-bump                   Skip bumping the version.
  --skip-changelog              Skip generating the changelog.
  --no-skip-ci                  Don't include "[skip ci]" in the commit messages. You can modify what the string is if you use a config file ("skipCiString").
  --skip-ci-in-tag              Add "[skip ci]" to the tag messages. You can modify what the string is if you use a config file ("skipCiString").
  --sftp-user <string>          SFTP user to use when publishing. (env: SFTP_USER)
  --sftp-host <string>          SFTP host (URL) to use when publishing. (env: SFTP_HOST)
  --sftp-remotedir <string>     SFTP directory (absolute path) to publish to. (env: SFTP_REMOTEDIR)
  --sftp-localdir <string>      Local directory to use when publishing. This should be a relative path from project folder. (env: SFTP_LOCALDIR)
  --sftp-pw <string>            SFTP password to use when publishing. (env: SFTP_PASSWORD)
  --sftp-port <number>          Port to use when publishing via SFTP. (env: SFTP_PORT)
  -h, --help                    display help for command

Shorthand instructions can be combined. For example, to do a verbose dry run in the current folder release -rv;

CLI arguments have the precedence over configuration files

API

import { ReleaseRunner } from '@madk/release';

const rr = new ReleaseRunner({
  // ...Config
})

rr.run();

Configuration

Besides the command line arguments, you can control the output of the release through configuration files (and environment variables).

To do so, create a configuration file in the project folder. This configuration file can be named one of the following (and prioritized in order). 1. ".release.cjs" 2. ".release.js" 3. "release.cjs" 4. "release.js"

You can also change what this is by passing in a configuration option through the cli or if running programmatically. CLI:

$ release --config config/my-own-config.js

Programmatically:

const rr = new ReleaseRunner({
  // ...
  config: 'my-own-config.js'
})

The file config value is a relative (child) file path from the root of the folder.

The file is javascript-based and must export a CommonJS-module:

module.exports = {
  // configuration
}

Build step

The build step is off by default. You can enable it either by using the build flag (-b, --build), or setting the setting the build property in a configuration file.

Examples:

# Build with default preset `npm run build`
$ release --build

# Build with custom command
$ release --build "npm run build:wasm"

module.exports = {
	// set to default preset, `npm run build`
	build: true,
	// set to custom command
	build: 'npm run build:wasm',
}

Bump step and "Bumpers"

The bump steps runs after successful tests. This step figures out if there is a new version. After that, the first "bumpers" are run. Bumpers makes it possible for youto provide custom functions to further update files that are not affected by the regular bump. These have to specified with a custom release-config file.

Bumpers per default is run after the bump step, but can also be set to be run after the build has been completed by setting when to build.

Example below can be used to update any files, here it is used to update files related to a WordPress-theme

// .release.cjs
const rx = /(stable\stag|version):\s*([0-9a-zA-Z-\.]*)$/gim;

const wpBump = (contents, runner) => {
	contents = contents.replace(rx, `$1: ${runner.project.nextVersion}`);

	return contents;
};

module.exports = {
	bumpers: [
		{
			file: 'readme.txt',
			callback: wpBump,
		},
		{
			file: 'style.css',
			callback: wpBump,
			skipStage: true // Skips this file as a part of the release commit
			// when: 'build' // You can modify when a bumper runs ('bump'/'build', corresponding to after those steps. If not set, it runs as 'bump')
		},
	],
}

Publish step

The publish step is off by default. You can enable it either by using the publish flag (-p, --publish), or setting the setting the publish property in a configuration file.

Examples:

# All default actions + publish with default preset `npm publish`
$ release --publish
$ release --publish npm

# All default actions + publish with SFTP
$ release --publish sftp

# All default actions + publish with custom command
$ release --publish "node custom-publish.js"

module.exports = {
	// Publish with default preset `npm publish`
	publish: true, // can also use 'npm'
	// Publish with SFTP
	publish: 'sftp',
	// set to custom command
	publish: 'node custom-publish.js',
}

SFTP Publishing

The SFTP publish uses ssh2-sftp-client.

You can use the CLI or env-variables to configure for basics setups. For a more advanced setup, use a configuration file and update the sftp-options there. The configuration are matching that of ssh2-sftp-client with the added properties:

localDir - Where, relative from the project folder, the sync should happen. Default is the current directory.
remoteDir - The absloute path to the remote directory we should sync to.

The publish happens through a basic synchronization of the folders: