Enhancement request to support putting the Jira issue number both in the header (pre-type, pre-description, post-description) and in the footer (post-body)

[schnitty]

Why?
I'm working for a client where we are using Jira for our tickets and Azure DevOps for repo, and pipelines.
When I configure the following tools to make the build, release and ticket integrations work:
https://marketplace.atlassian.com/apps/4984/git-integration-for-jira?hosting=cloud&tab=overview
https://marketplace.atlassian.com/apps/1220515/azure-pipelines-for-jira?hosting=cloud&tab=overview

Through my testing I've found:
That the deployments are only linked to the Jira tickets if the Jira ticket reference is in the header of the commit
That the links to the commits in Jira tickets are only present if the Jira ticket reference is in the footer of the commit

Go figure?
So to get what I'm looking for (navigability from Jira to Azure DevOps for issues, builds, releases) I need it both places.

For my own purposes it was easy enough to modify what you have to make that work by doing the following:
(only code changed is under the comment, provided the rest for context)

var getJiraIssueLocation = function(location, type, scope, jiraWithDecorators, subject) {
    switch(location) {
      case 'pre-type':
        return jiraWithDecorators + type + scope + ': ' + subject;
        break;
      case 'pre-description':
        return type + scope + ': ' + jiraWithDecorators + subject;
        break;
      case 'post-description':
        return type + scope + ': ' + subject + ' ' + jiraWithDecorators;
        break;
      case 'post-body':
        // return type + scope + ': ' + subject;
        return type + scope + ': ' + jiraWithDecorators + subject;
        break;
      default:
        return type + scope + ': ' + jiraWithDecorators + subject;
    }
  };

and

{
    type: 'limitedInput',
    name: 'subject',
    message: 'Write a short, imperative tense description of the change:',
    default: options.defaultSubject,
    maxLength: maxHeaderWidth - (options.exclamationMark ? 1 : 0),
    leadingLabel: answers => {
      // const jira = answers.jira && options.jiraLocation !== 'post-body' ? ` ${answers.jira}` : '';
      const jira = answers.jira && options.jiraLocation !== 'post-body' ? ` ${answers.jira}` : ` ${answers.jira}`;
    
      let scope = '';
      const providedScope = getProvidedScope(answers);
      if (providedScope && providedScope !== 'none') {
        scope = `(${providedScope})`;
      }
    
      return `${answers.type}${scope}:${jira}`;
    },
    validate: input =>
      input.length >= minHeaderWidth ||
      `The subject must have at least ${minHeaderWidth} characters`,
    filter: function(subject) {
      return filterSubject(subject);
    }
},

But obviously if you were looking to add as an enhancement you would want to provide it as a whole other option and do it properly.
It isn't clear however how you might want to do that as once you start considering an option of both you then double the options that you currenlty offer (pre-type and post-body), (pre-description and post-body) ... and it starts to get a bit unweildy.

For what you consider an edge case it might not be worth it for you but I thought I would post this anyway for you to consider.
For now my simple hack works for me.

[juliuscc]

A very interesting problem... 🤔

I agree that I have no idea how to provide this in a nice API. At that point I would probably prefer a template option where you can provide any template you want.

[schnitty]

As I've thought about it a bit more it might be as simple as adding an extra boolean config option named something like (jiraLocationBoth, JiraLocationHeaderAndFooter) I admit names could be better. Whatever it is called, if you pick a location option that is in the header/subject i.e: pre-type or pre-description or post-description and also set JiraLocationBoth to true it would also put the Jira ticket post-body (in the footer), default value of jiraLocationBoth would be false. There are still a few issues with this in that your locations that are in the header/subject use names of type and description and also if post-body was selected then setting jiraLocationBoth to true would have no effect, which wouldn't be what people would be expecting. This could be mitigated a little bit with some validation on the field that makes it so that you can only set jiraLocationBoth to true if you have also set jiraLocation to something other than post-body and as well through documentation but it isn't that elegant of a solution. It does have the benefit though of not being a breaking change.

If you were to refactor to have the concept of jiraLocationInHeader (pre-type, pre-description, post-description, none) and jiraLocationInFooter (post-body, none) it would make a little more sense but would be a breaking change.

[schnitty]

I've come up with a simpler solution and will have a PR for it ready today.
simply adding three more locations:

pre-type-and-post-body
pre-description-and-post-body
post-description-and-post-body

keeps the code clean, is not a breaking change and doesn't mix and confuse locations.

[juliuscc]

Do you think there would ever be a need for pre-type-and-pre-body, pre-description-and-pre-body, etc?

[juliuscc]

TBH I think we are starting to get more and more complicated requests, that muddle up the API little by little. I would prefer advanced users to have a templating option. Probably something based on mustache or something else lightweight.

I can still be convinced that I am wrong but I am leaning towards declining any more advanced use cases and instead suggesting a PR that adds templating. Maybe even remove some of the current options. WDYT?

[schnitty]

Do you think there would ever be a need for pre-type-and-pre-body, pre-description-and-pre-body, etc?

I don't think so.
Jira and integrations with it seem to have this preference for putting tickets in the header (subject) whereas conventional changelog has issue references in the footer. So I don't see a case for having Jira issue references multiple times in the the header.

[schnitty]

TBH I think we are starting to get more and more complicated requests, that muddle up the API little by little. I would prefer advanced users to have a templating option. Probably something based on mustache or something else lightweight.

I can still be convinced that I am wrong but I am leaning towards declining any more advanced use cases and instead suggesting a PR that adds templating. Maybe even remove some of the current options. WDYT?

A templating solution using handlebars templating or similar is certainly an option. I guess the challenge is in gettinng the right balance between simple API and providing the flexibiliity that people require. It can be easy to get it wrong on both sides. Too simple an API and people have to revert to the advanced scenario too often, too complicated an API and it starts getting too hard to use and understand.

You're best placed to make that call based on who you see as the target audience for your tool.

The only advice I could give is don't make the advanced scenario the only scenario. Just because you can do everything with a templating engine or writing your own preset doesn't mean that should be the only way to do it, because at that point for some, they may as well code their own tool.

Maybe your approach of limiting the direct options in the tool to the 90% and moving the remaining 10% to a template solution is a good balance to strike.

A happy compromise would also be to take these types of cases (the 10%) and provide examples in the documentation of how to achieve them. Not everyone who uses, or wants to use these types of tools knows node or templating libraries for that matter but if they have some simple examples of how to solve real world problems with it, then that helps the tool adoption.

Hopefully my input helps...

As for the PR, happy for you to make the call on how you want to progress the design of your tool. I've created what I did for my purposes and am happy to use my fork for what I need at this client. Turned out to be a pretty small code change, thanks for the massive headstart!

[juliuscc]

I think that was very valid feedback! Thanks!

I especially like the idea of documenting common cases with examples.

It's always a difficult tradeoff on what to support in the direct options vs advanced templating. I think how I would like it to work is that the direct options should be self explanatory. So if any option is not obvious it should probably just be a part of the template.

Another way of thinking about it is having options that are expected. Without looking at the documentation, what options would make sense for a random developer.

With that said, both ways of thinking require subjective evaluation. And also I think some of the options we support today should be removed based on those requirements.

[juliuscc]

I do also hope that the "advanced case" is simple enough that it might even cover more than 10% of the cases. My gut feel tells me that there is a long tail of cases that are very non-standard. Just based on all PRs we regularly get for odd cases.

And that long tail is probably much more than 10%