changesets-format-with-issue-links

Changesets Format with Git Links

What is this?

Atlassian Changesets is a changelog management tool. Its default formatter generates a plain list of changes, without issue links.

This package adds links to the git commits, issues, and pull requests where your changesets were added.

The result is similar to the output of other common changelog standards, such as standard-version and Release Please.

Setup

If you have already set up Changesets, you only need to install the package and add it to your .changeset/config.json.

You do not need to enable the commit option in your config.

npm install --D changesets-format-with-issue-links

// .changeset/config.json
{
  "changelog": [
    "changesets-format-with-issue-links",
    {
      "repoBaseUrl": "https://github.com/your-username/repo",
      // additional options here
    }
  ]
}

Bitbucket setup

You can change the commit and issue link templates for Bitbucket or any other service:

// .changeset/config.json
{
  "changelog": [
    "changesets-format-with-issue-links",
    {
      "repoBaseUrl": "https://bitbucket.org/your-company/repo",
      // This will generate a Markdown link like `[#123](https://bitbucket.org/your-company/repo/pull-requests/123)`,
      // wrapped in parentheses.
      "issueTemplate": " ([#$issue]($repoBaseUrl/pull-requests/$issue))"
      "commitTemplate": " [$abbrevHash]($repoBaseUrl/commits/$hash)"
    }
  ]
}

Options

repoBaseUrl (required)

A base url -- including https -- which can be used to build links in commitTemplate and issueTemplate. Example: "https://github.com/spautz/changesets-changelog-format"

changesetTemplate (default: "- ${changesetTitle}${issue}${commit}${changesetBody}")

Content that will be added to your changelog.

With the default value, issue and commit links will be inserted at the end of the first line of your changeset message.

See commitTemplate for the $commit variable, issueTemplate for the $issue variable, and Template Variables for other available values.

commitTemplate (default: " ([$abbrevHash]($repoBaseUrl/commit/$hash))")

Content for the $commit variable, based on the commit when the changeset was created. See gitlogOptions below for information on the available fields from the commit.

commitMissingTemplate (default: "")

Content for the $commit variable when no commit could be found. This should generally be left blank.

issuePattern (default: "#(\\d+)\\)")

Regular expression (without the leading and trailing /) used to identify issues and pull requests in the subject line of a commit message. The default will match a number immediately followed by a closing parentheses, like #4).

If the commit message matches this pattern, the Regex result will be available as $issueMatch and the text inside the capturing group ((\d+) in the default) will be available as $issue in the issueTemplate, below.

issueTemplate (default: " ([#$issue]($repoBaseUrl/issues/$issue))")

Content for the $issue variable, based on the value matched by issuePattern.

issueMissingTemplate (default: "")

Content for the $issue variable when no issue or pull request could be found. This should generally be left blank.

gitlogOptions

Default:

{
  "repo": ".",
  "fields": ["hash", "abbrevHash", "authorName", "authorEmail", "authorDate", "subject"],
  "includeMergeCommitFiles": true
}

Options passed to gitlog (see docs here).

This can be used to add additional fields to the template, or to change the behavior of the git log search.

How it works

This works by identifying the git commit when a changeset entry was added, looking for an issue number in its commit message, and then using templates to append any relevant links or info to the changelog entry.

Template variables

Inside any of the templates (changesetTemplate, commitTemplate, commitMissingTemplate, issueTemplate, or issueMissingTemplate), any token that starts with $ or which is wrapped within ${...} will be treated as a variable.

Use \\$ to escape the dollar sign character if you do not want it to be treated as a variable.

Available variables

Information from the changeset entry:

Variable name	Notes
$changesetTitle	The summary (first line) of your Changesets entry
$changesetBody	All text after the first line of your Changesets entry, trimmed
$changesetRawBody	The entire text of your Changesets entry
$versionType	The semver bump type: "major", "minor", "patch", or "none"
$changesetInfo	Object containing all of the above, plus any other information from Changesets (e.g.,${changesetInfo.changesetTitle}, ${changesetInfo.versionType})

Information from the git commit when the changeset was added:

Variable name	Notes
$commit	Text generated from commitTemplate (or commitMissingTemplate if the commit was not found)
$hash	The full 40-character git hash
$abbrevHash	The short git hash
$subject	First line of the commit message
...	Anything you requested via gitlogOptions.fields
$commitInfo	Object containing all of the above (e.g., ${commitInfo.abbrevHash}, ${commitInfo.hash})

Information from the matched issue pattern, if any:

Variable name	Notes
$issue	Text generated from issueTemplate (or issueMissingTemplate if no issue was found)
$issueMatch	Object containing all of the results from the match against issuePattern (e.g., ${issueMatch[1]})

And also any additional values you included in the config options:

Variable name	Notes
$repoBaseUrl	Generally used by commitTemplate and issueTemplate
...	Anything that wasn't recognized
$options	Object containing all of the options from .changeset/config.json, merged with the defaults