Breaking: replace bump with cc add command

Existing behavior remains the same, so `hallmark cc add <target>`
does the same as `hallmark bump <target>` did.

The new command is more generic however: it also supports inserting
a release into the changelog for an existing version (regardless of
whether that version is first, last or somewhere in the middle).

In addition, there's a new option `--no-commits` to skip populating
the release with commits. Effectively only creating a markdown
heading (with a version number, link and date).

Closes #84

Author: vweevers

README.md

@@ -20,6 +20,10 @@
 - [Requirements](#requirements)
 - [Rules](#rules)
 - [Usage](#usage)
+  - [Commands](#commands)
+    - [`lint`](#lint)
+    - [`fix`](#fix)
+    - [`cc add <target>`](#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 <target>`: 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 <target>`
+
+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:

USAGE

@@ -9,8 +9,8 @@ Commands:
 
   lint                      Lint markdown files (default)
   fix                       Fix markdown files
-  bump <target>             Add new entry to changelog. Target must be a
-                            release type (major, minor, patch, premajor,
+  cc add <target>           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 <reporter>   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

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()
+  }
 }

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
   }

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