From a92ba3549697c703d0262027b25c53e011cfd4ba Mon Sep 17 00:00:00 2001 From: Vincent Weevers Date: Thu, 4 Apr 2024 13:32:22 +0200 Subject: [PATCH] Take structured information from git trailers (#115) --- README.md | 27 ++++++++++++++++++++++++++- package.json | 2 +- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d606ebf..270a6e4 100644 --- a/README.md +++ b/README.md @@ -185,10 +185,35 @@ Additional options for this command: Multiple targets can be provided, in no particular order. For example `hallmark cc add 1.1.0 1.2.0` which acts as a shortcut for `hallmark cc add 1.1.0 && hallmark cc add 1.2.0`. -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. +Works best on a linear git history without merge commits. If `hallmark` encounters other tags in the commit range it will stop there and not include further (older) commits. The `cc add` command also fixes markdown (both existing content and generated content) but only in `CHANGELOG.md`. After you tweak the release following [Common Changelog](https://common-changelog.org) you may want to run `hallmark fix`. +Git [trailers](https://git-scm.com/docs/git-interpret-trailers) ("lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message") can provide structured information to the generated changelog. The following trailer keys are supported (case-insensitive): + +- `Category`: one of `change`, `addition`, `removal`, `fix`, or `none`. If `none` then the commit will be excluded from the changelog. If not present then the change will be listed under Uncategorized and will require manual categorization. +- `Notice`: a [notice](https://common-changelog.org/#23-notice) for the release. If multiple commits contain a notice, they will be joined as sentences (i.e. ending with a dot) separated by a space. +- `Ref`, `Refs`, `Fixes`, `Closes` or `CVE-ID`: a numeric reference in the form of `#N`, `PREFIX-N` or `CVE-N-N` where `N` is a number and `PREFIX` is at least 2 letters. For example `#123`, `GH-123`, `JIRA-123` or `CVE-2024-123`. Can be repeated, either with multiple trailer lines or by separating references with a comma - e.g. `Ref: #1, #2`. Non-numeric references are ignored. +- `Co-Authored-By`: co-author in the form of `name `. Can be repeated. + +For example, the following commit (which has Bob as git author, let's say): + +``` +Bump math-utils to 4.5.6 + +Ref: JIRA-123 +Category: change +Co-Authored-By: Alice +``` + +Turns into: + +```md +## Changed + +- Bump math-utils to 4.5.6 (d23ba8f) (JIRA-123) (Bob, Alice) +``` + #### `cc init` Create a `CHANGELOG.md` from scratch. Inserts releases for every (semver-valid) git tag and then populates them with commits. If no git tags exist then the resulting `CHANGELOG.md` will merely have a `# Changelog` heading, without releases. diff --git a/package.json b/package.json index 5594934..42f2036 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ "remark": "^14.0.1", "remark-autolink-references": "^2.0.0", "remark-collapse": "~0.1.2", - "remark-common-changelog": "^2.2.0", + "remark-common-changelog": "^2.3.0", "remark-gfm": "^3.0.1", "remark-github": "^11.2.2", "remark-lint": "^9.1.0",