feat: Add config for issue tracker references

[markmsmith]

Background

As requested by @bcoe in https://github.com/conventional-changelog/standard-version/issues/154#issuecomment-500071172, this ticket is to add a variable to the spec to allow configuring the parsing of issue references. This complements the existing configuration option issueUrlFormat, by allowing configuration of the parser to match the format of the issue tracker they're using. To give a concrete example, many projects use Jira for their issue tracker, so the issue references in a commit message will be in the format PRJ-123 rather than github's #123.

For my use case, it would be sufficient to expose the variable issuePrefixes that the parser already supports, but I could envision more advanced users wanting the ability to supply a function that is passed the whole commit message and returns a list of issue IDs. I'm fine if that's out of scope / a future increment though.

One snag I realized in the course of writing this up, github issue URLs are pretty simple, in that you can just parse out the ID from #123 and then blindly slap that into the issueUrlFormat of https://github.com/<user>/<repo>/issues/<id>, which results in .../issues/123, but jira IDs are qualified by the project, so have to include the prefix in the url, eg https://<my issue tracker/browse/PRJ-123. This will be a problem, since the default parsing would result in the incorrect url https://<my issue tracker/browse/123. You can work around if it you're just dealing with a single project by adding the prefix in to the issueUrlFormat, but if you have multiple (as supported by issuePrefixes being an array) then you're kind of stuck due to information being lost.

Two alternative solutions I can think of are:
a) Add an additional boolean variable, includeIssuePrefix, that defaults to false, which specifies whether the id placeholder in the issueUrlFormat includes the prefix or not b) Add an alternative placeholder, idWithPrefix, allowing the user to use that as the placeholder instead of id (but they would have to override issueUrlPrefix to use it).

I have a slight preference for a), since it means a user can still take advantage of the issue url being automatically resolved from the package.json, rather than having to duplicate that information like you have to do in approach b), but I could live with either.

Proposal

issuePrefixes
Type: `array` of `string`, or `string`. Default: ['#']
An array of prefixes that should be used when scanning a commit for issue references.
Example: ['PRJA-', 'PRJB-', 'PRJC-']

includeIssuePrefix
Type: `boolean`.  Default: false
Controls whether the parsed issuePrefix (as specified in `issuePrefixes`) should be included in the `id` placeholder when constructing the urls for issues referenced in a commit (as controlled by `issueUrlFormat`).  This is useful if you are using an issue tracker (such as Jira) that requires the issue ID to include the prefix as a qualifier, eg
`jira.mycompany.com/browse/PRJ-123` rather than the default of `jira.mycompany.com/browse/123`

alternative b)

issueWithPrefix
An alternative placeholder to use in the `issueUrlFormat` configuration, instead of `id`, which includes the parsed prefix.  This is useful if you are using an issue tracker (such as Jira) that requires the issue ID to include the prefix as a qualifier, eg
`jira.mycompany.com/browse/PRJ-123` rather than `jira.mycompany.com/browse/123`

[mascah]

I've come down this same road and ended up on using a jenky sed call in my postchangelog lifecycle. Currently I'm fortunate to only have to reference a single Jira project across many git repos, so that makes life slightly easier. Regardless, I think option a) is reasonable.

Looking forward to this enhancement, and thanks for taking the time with this!

[bcoe]

@markmsmith @mascah would love to add this feature :+1: please keep me in the loop if anyone has time to contribute a patch.

[tommywo]

I've created a pull request to conventional-changelog which makes it properly reference to stash and jira with config like this:

'use strict'

const base = require(`conventional-changelog-conventionalcommits`)

module.exports = base({
  issuePrefixes: ['JIRAPROJECT-'],
  commitUrlFormat: '{{host}}/projects/{{owner}}/repos/{{repository}}/commits/{{hash}}',
  issueUrlFormat: 'https://jira.example.com/browse/{{prefix}}{{id}}',
  compareUrlFormat: '{{host}}/projects/{{owner}}/repos/{{repository}}/compare/commits?sourceBranch=refs%2Ftags%2F{{currentTag}}&targetBranch=refs%2Ftags%2F{{previousTag}}'
})

[markmsmith]

I think there are some issues with this approach, as it either a) breaks github urls, since the # prefix shouldn't be included, or b) requires people override the issueUrlFormat, instead of just setting includeIssuePrefix and having that be applied for you.

[stefanbuck]

I'm currently working on a GitHub app which is somewhat related to this. It automatically adds a badge to the Pull Requests description that links to the related JIRA ticket.

The app is in private beta right now. Please drop me a DM if you want to join the beta group

https://twitter.com/buckstefan/status/1147620338584473602