npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@goodrequest/jira-changelog

v2.2.7

Published

Generates a changelog by matching git commits to Jira tickets.

Downloads

182

Readme

Jira Changelog Generator

Generates a changelog of Jira issues from your git history and, optionally, attach all issues to a release.

For example:

$ jira-changelog --range origin/prod...origin/master
Jira Tickets
---------------------

  * <Bug> - Unable to access date widget
    [DEV-1234] https://yoursite.atlassian.net/browse/DEV-1234

  * <Story> - Support left-handed keyboards
    [DEV-5678] https://yoursite.atlassian.net/browse/DEV-5678

  * <Story> - Search by location
    [DEV-8901] https://yoursite.atlassian.net/browse/DEV-8901

Other Commits
---------------------

  * <cd6f512> - Fix typo in welcome message

Pending Approval
---------------------
 ~ None. Yay! ~

You can also have it automatically post to slack!

How it works

The script looks for Jira issue keys, surrounded by square brackets (i.e. [DEV-123]), in the git commit logs. When it finds one, it associates that Jira issue ticket with that commit and adds it to the changelog.

Installation

npm install -g jira-changelog

JIRA setup

Before configuring the app, register a new user in Jira for the app to use to retrieve and update tickets. Then create an Auth Token for this user, which will be used for authentication. Jira no longer supports authenticating with password for API calls.

Configuration

Create a file called changelog.config.js and put it at the root of your git workspace directory. This is also where you'll call the jira-changelog command from.

Here's a simple example with sample Jira API values:

module.exports = {
	jira: {
		api: {
			host: 'myapp.atlassian.net',
			email: '[email protected]',
			token: 'qWoJBdlEp6pJy15fc9tGpsOOR2L5i35v',
			options: {}
		}
	}
}

The token is the API token assigned to this user. To see all values supported, look at the changelog.config.js file at the root of this repo.

Use the options object to set jira-client options. See official docs for available options.

Usage

jira-changelog --range origin/prod...origin/master

Assuming you deploy from a branch named prod, this will generate a changelog with all commits after the last production deploy to the current master version (You can change the default branch names with the sourceControl.defaultRange object, in your config).

jira-changelog

Alternatively, you can specify a range (using git commit range format) in the command:

jira-changelog --range origin/prod...origin/stage

Releases

You can automatically attach a release to all Jira issues in the changelog with the --release flag. For example, let's say we want to add all issues in the changelog to the "sprint-12" release:

jira-changelog --release sprint-12

This will set the fixVersions of all issues to "sprint-12" in Jira.

Slack

The script can also automatically post the changelog to slack.

First, get an API token from Slack for your workspace: https://api.slack.com/tokens

Then add slack to your configuration file:

module.exports = {
  ...
  slack: {
    apiKey: 'asdlfkjasdoifuoiucvlkxjcvoixucvi',
    channel: '#changelogs'
  },
}
  • Add your API token to slack.apiKey.
  • slack.channel is the channel you want the script to send the changelog to.

Then simply add the --slack flag to the command:

jira-changelog --slack

API

The code used to generate the changelogs can also be used as modules in your node app. See the module source for documentation.

For example:

npm install -S jira-changelog
const Config = require('jira-changelog').Config
const SourceControl = require('jira-changelog').SourceControl
const Jira = require('jira-changelog').Jira

const gitRepoPath = '/home/user/source/'

// Get configuration
const confPath = `${gitRepoPath}/changelog.config.js`
const config = Config.readConfigFile('/Users/jeremygillick/Source/app/changelog.config.js')

// Get commits for a range
const source = new SourceControl(config)
const range = {
	from: 'origin/prod',
	to: 'origin/master'
}
source.getCommitLogs(gitRepoPath, range).then((commitLogs) => {
	// Associate git commits with jira tickets and output changelog object
	const jira = new Jira(config)
	jira.generate(commitLogs).then((changelog) => {
		console.log(changelog)
	})
})

Tips & Tricks

Change the output

The output of the changelog is controlled by an ejs template defined in your changelog.config.js file. You can see the default template, here: https://github.com/jgillick/jira-changelog/blob/master/changelog.config.js#L95-L136

The data sent to the template looks like this:

{
  jira: {
    baseUrl: "...",
    releaseVersions: [],
  },
  commits: {
    all: [],       // all commits
    tickets: [],   // commits associated with jira tickets
    noTickets: [], // commits not associated with jira tickets
  },
  tickets: {
    all: [],       // all tickets
    approved: [],  // tickets marked as approved
    pending: [],   // tickets not marked as approved
    pendingByOwner: [], // pending tickets arranged under ticket reporters.
  }
}

The template should output data only, not perform data transformations. For that, define the transformData or transformForSlack functions.

Custom data transformation

What if you want to edit the git commit log messages to automatically add links around the ticket numbers? You can do that, and more, by defining the transformData function inside your changelog.config.js file. This function can transform all the template data, before it is sent to the template.

For example, adding a link around all ticket numbers in the git logs would look something like this (overly simplistic, for example only):

transformData: (data) => {
  // Link the ticket numbers in all commit summaries.
  data.commits.all.forEach((commit) => {
    commit.summary = commit.summary.replace(
      /\[([A-Z]+\-[0-9]+)\]/,
      '[<a href="https://YOU.atlassian.net/browse/$1">$1</a>]'
    );
  });
  return data;
},

Then, if you want to create slack specific data transformations, define the transformForSlack function. This function will be called after transformData.