diff --git a/README.md b/README.md index abcaed9..6b5e38b 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,10 @@ - [Requirements](#requirements) - [Rules](#rules) - [Usage](#usage) + - [Commands](#commands) + - [`lint`](#lint) + - [`fix`](#fix) + - [`cc add `](#cc-add-target) - [Package Options](#package-options) - [`ignore`](#ignore) - [`autolinkReferences`](#autolinkreferences) @@ -65,10 +69,11 @@ Fix custom files: hallmark fix CHANGELOG.md docs/*.md ``` -Add new minor version to changelog: +Add new minor version or existing version to changelog, optionally without content: ``` -hallmark bump minor +hallmark cc add minor +hallmark cc add 4.2.0 --no-commits ``` ## What You Might Do @@ -134,13 +139,9 @@ README.md:5:3 `hallmark [command] [options] [pattern ...]` -Lint or fix files in the current working directory. By default `hallmark` includes files matching `*.md`. Pass one or more glob patterns to override this. Files matching `.gitignore` patterns are ignored. To ignore additional files, use the `--ignore / -i` option. +Lint or fix files in the current working directory. The default command is `lint`. -Commands: - -- `lint`: lint markdown files (default) -- `fix`: fix markdown files -- `bump `: add new entry to changelog. Target must be a release type (major, minor, patch, premajor, preminor, prepatch, prerelease) or a version. +By default `hallmark` includes files matching `*.md`. Pass one or more glob patterns to override this. Files matching `.gitignore` patterns are ignored. To ignore additional files, use the `--ignore / -i` option. Options: @@ -151,6 +152,37 @@ Options: - `--[no-]color`: force color in report (detected by default) - `--fix`: backwards-compatible alias for fix command +### Commands + +#### `lint` + +Lint markdown files. + +#### `fix` + +Fix markdown files in place. + +#### `cc add ` + +Add a release to `CHANGELOG.md` and populate it with commits. The `target` must be one of: + +- A release type: `major`, `minor`, `patch`, `premajor`, `preminor`, `prepatch`, `prerelease` + - These take the current version from the semver-latest tag, release or `package.json` (whichever is greatest if found) and bump it + - The `major` type bumps the major version (for example `2.4.1 => 3.0.0`); `minor` and `patch` work the same way. + - The `premajor` type bumps the version up to the next major version and down to a prerelease of that major version; `preminor` and `prepatch` work the same way. + - The `prerelease` type works the same as `prepatch` if the current version is a non-prerelease. If the current is already a prerelease then it's simply incremented (for example `4.0.0-rc.2` to `4.0.0-rc.3`). +- A [semver-valid](https://semver.org/) version like 2.4.0. + +If the (resulting) version is greater than the current version then commits will be taken from the semver-latest tag until HEAD. I.e. documenting a new release before it's git-tagged. If the version matches an existing tag then a release will be inserted at the appriopriate place, populated with commits between that version's tag and the one before it. I.e. documenting a past release after it's git-tagged. + +Additional options for this command: + +- `--no-commits`: create an empty release. + +Works best on a linear git history. If `hallmark` encounters other tags in the commit range (which may happen if releases were made in parallel on other branches) it will stop there and not include further (older) commits. + +The `cc add` command also fixes markdown - both existing content and generated content. After you tweak the release following [Common Changelog](https://common-changelog.org) you may want to run `hallmark fix` again. + ## Package Options You can add a `hallmark` object to your `package.json` with additional configuration. For example: diff --git a/USAGE b/USAGE index dfd071d..990a174 100644 --- a/USAGE +++ b/USAGE @@ -9,8 +9,8 @@ Commands: lint Lint markdown files (default) fix Fix markdown files - bump Add new entry to changelog. Target must be a - release type (major, minor, patch, premajor, + cc add Add new release to CHANGELOG.md. Target must be + a release type (major, minor, patch, premajor, preminor, prepatch, prerelease) or a version. Options: @@ -21,6 +21,7 @@ Options: --report Specify reporter --[no-]color Force color in report (detected by default) --fix Backwards-compatible alias for fix command + --no-commits Don't populate release with commits Examples: @@ -34,4 +35,4 @@ Examples: $ hallmark fix CHANGELOG.md docs/*.md # Add new minor version to changelog - $ hallmark bump minor + $ hallmark cc add minor diff --git a/cli.js b/cli.js index ba27804..74a11a0 100644 --- a/cli.js +++ b/cli.js @@ -7,12 +7,13 @@ if (process.version.match(/^v(\d+)\./)[1] < 10) { } const argv = require('subarg')(process.argv.slice(2), { - boolean: ['fix', 'help', 'version'], + boolean: ['fix', 'help', 'version', 'commits'], string: ['report'], default: { fix: false, help: false, - version: false + version: false, + commits: true }, alias: { h: 'help', @@ -22,33 +23,36 @@ const argv = require('subarg')(process.argv.slice(2), { }) if (argv.help) { - usage() + usage(0) } else if (argv.version) { console.log(require('./package.json').version) } else { - const rest = argv._ + const { commits, _: rest, ...options } = argv if (rest[0] === 'lint') { - argv.files = files(rest.slice(1)) - require('./index.js').lint(argv, done) + options.files = files(rest.slice(1)) + require('./index.js').lint(options, done) } else if (rest[0] === 'fix') { - argv.files = files(rest.slice(1)) - require('./index.js').fix(argv, done) + options.files = files(rest.slice(1)) + require('./index.js').fix(options, done) } else if (rest[0] === 'bump') { - const target = rest[1] - - if (!target) { - usage() - process.exit(1) + console.error("Error: the 'bump' command has been renamed to 'cc add'.\n") + usage(1) + } else if (rest[0] === 'cc') { + if (rest[1] === 'add') { + const target = rest[2] + if (!target) usage(1) + options.files = files(rest.slice(3)) + require('./index.js').cc.add(target, { ...options, commits }, done) + } else { + console.error('Error: unknown command.') + usage(1) } - - argv.files = files(rest.slice(2)) - require('./index.js').bump(target, argv, done) } else { // Old usage (no commands) // TODO: deprecate? - argv.files = files(rest) - require('./index.js')[argv.fix ? 'fix' : 'lint'](argv, done) + options.files = files(rest) + require('./index.js')[options.fix ? 'fix' : 'lint'](options, done) } } @@ -61,10 +65,16 @@ function done (err, result) { process.exit(result.code) } -function usage () { +function usage (exitCode) { const fs = require('fs') const path = require('path') - const usage = path.join(__dirname, 'USAGE') + const usage = fs.readFileSync(path.join(__dirname, 'USAGE'), 'utf8').trim() - fs.createReadStream(usage).pipe(process.stdout) + if (exitCode) { + console.error(usage) + process.exit(exitCode) + } else { + console.log(usage) + process.exit() + } } diff --git a/index.js b/index.js index b3ae3a6..e2f6387 100644 --- a/index.js +++ b/index.js @@ -137,7 +137,8 @@ exports.fix = function (options, callback) { return hallmark({ ...options, fix: true }, callback) } -exports.bump = function (target, options, callback) { +exports.cc = {} +exports.cc.add = function (target, options, callback) { if (!target) { throw new TypeError('First argument "target" is required') } else if (typeof target !== 'string') { @@ -152,6 +153,7 @@ exports.bump = function (target, options, callback) { } const changelog = { + commits: options.commits !== false, ...options.changelog, add: target } diff --git a/package.json b/package.json index 76cf6fa..aa31b0a 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,7 @@ "remark": "^12.0.1", "remark-autolink-references": "^1.0.0", "remark-collapse": "~0.1.2", - "remark-common-changelog": "^0.0.2", + "remark-common-changelog": "^0.0.3", "remark-github": "^9.0.1", "remark-lint": "^7.0.1", "remark-lint-blockquote-indentation": "^2.0.1",