@invitation-homes/release-notes

@invitation-homes/release-notes

Generates release notes from hosted services (such as GitHub and Jira) in one of the following formats:

• markdown
• html
• json

Installation

First, make sure your home directory has a .npmrc file with GitHub Personal Access Token:

# ~/.npmrc
//npm.pkg.github.com/:_authToken=<your_personal_access_token>

Note: your GitHub Personal Access Token needs at least "read" permissions for packages, and should be authorized for use with the Invitation Homes GitHub Organization.

Next, configure your project to use the GitHub Packages Registry for this package:

# <projectRoot>/.npmrc
@invitation-homes:registry=https://npm.pkg.github.com

Then install:

yarn:

yarn add -D @invitation-homes/release-notes

Usage

Quick Start - Use built-in Configured Integrations!

Integrations save you time by fetching data for you from source control and project management tools.

Integration Type	Available Configured Integrations
Source Control	github
Project Management Tool	jira

Example: GitHub & Jira

Set the environment variables needed for the GitHub and Jira Configured Integrations:

# GitHub Token
SCM_TOKEN=<your_github_token>

# Jira Tokens
PROJECT_MGMT_BASE_URL=<your_jira_base_url> # ex: https://invitationhomes.atlassian.net
PROJECT_MGMT_USERNAME=<your_jira_username_or_email>
PROJECT_MGMT_TOKEN=<your_jira_api_token>

Generate the diff and format the output:

import * as releaseNotes from '@invitation-homes/release-notes';
import type { FetchCommitsIntegration, FetchStoryDataIntegration } from '@invitation-homes/release-notes';

async function createReleaseNotes(repository: string, start: string, end: string): Promise<string> {
  const githubConfig: FetchCommitsIntegration = { source: 'github', repository, start, end };
  const jiraConfig: FetchStoryDataIntegration = { source: 'jira' };
  const outputFormat = 'md'; // 'md' | 'html' | 'json'
  const version = '1.0.0';

  const diff = await releaseNotes.generate(githubConfig, jiraConfig);
  const output = releaseNotes.format(diff, outputFormat, {
    name: `${repository} v${version}`,
    repositoryOwner: 'invitation-homes',
    repository,
  });

  return output;
}

GitHub

Required Environment Variables

Variable	Description
SCM_TOKEN	An API token for GitHub. Used to fetch commits from a repository for given start and end points.

Jira

Required Environment Variables

Variable	Description
PROJECT_MGMT_BASE_URL	The base url of your Jira organization.
PROJECT_MGMT_USERNAME	Jira username or email.
PROJECT_MGMT_TOKEN	Jira API token associated with the username.

Custom Configuration

If you're using a source control system or project management tool other than those provided as configured integrations, you can create custom configuration functions.

import * as releaseNotes from '@invitation-homes/release-notes';
import type { FetchCommits, FetchStoryData } from '@invitation-homes/release-notes';

async function createReleaseNotes(repository: string, start: string, end: string): Promise<string> {
  const diff = await releaseNotes.generate(fetchCommits, fetchStoryData);
  const output = releaseNotes.format(diff, 'md', {
    name: `${repository} v1.0.0`,
    repositoryOwner: 'invitation-homes',
    repository,
  });

  return output;
}

async function fetchCommits(): FetchCommits {
  /*
    return an array of objects with shape: 
    { 
      sha: <commit_sha>,  // string
      message: <commit_message_with_jira_key> // string
    }
  */
}

async function fetchStoryData(storyId: string): FetchStoryData {
  /*
    return an object with shape: 
    { 
      storyId: <story_id>, // string
      url: <link_to_story>, // string
      summary: <title_or_short_summary_of_story>, // string
      status: <story_status>, // string, ex: "Ready" or "Done"
      type: <type_of_story>, // string, ex: "Bug", "Story", "Chore", "Task", etc.
    }
  */
}

Custom Auth

If your workspace doesn't support environment variables, you can either (a) implement custom configuration/s, or (b) add a custom function to the configured integration that returns the necessary variables. For example:

import * as releaseNotes from '@invitation-homes/release-notes';
import type { FetchCommitsIntegration, FetchStoryDataIntegration } from '@invitation-homes/release-notes';

async function createReleaseNotes(repository: string, start: string, end: string): Promise<string> {
  const githubConfig: FetchCommitsIntegration = {
    source: 'github',
    repository,
    start,
    end,
    getAuthParams: () => ({
      SCM_TOKEN: '<your_github_token>', // ex: get this from the parameter store if implementing a lambda function
    }),
  };
  const jiraConfig: FetchStoryDataIntegration = {
    source: 'jira',
    getAuthParams: () => ({
      PROJECT_MGMT_BASE_URL: '<your_jira_base_url>', // ex: get this from the parameter store if implementing a lambda function
      PROJECT_MGMT_USERNAME: '<your_jira_username_or_email>',
      PROJECT_MGMT_TOKEN: '<your_jira_api_token>',
    }),
  };

  const diff = await releaseNotes.generate(githubConfig, jiraConfig);
  const output = releaseNotes.format(diff, 'md', {
    name: `${repository} v'1.0.0'`,
    repositoryOwner: 'invitation-homes',
    repository,
  });

  return output;
}

Project Folder Structure

src
|-- index.ts
|-- types.ts
|-- format
|   ├-- index.ts
|   ├-- utils.ts
|   └-- types.ts
|-- generate
|   ├-- index.ts
|   └-- utils.ts
|-- integrations
|   ├-- index.ts
|   ├-- pmt
|   |   └-- jira.ts
|   └-- scm
|       └-- github.ts

• /src/index.ts - main entry point, responsible for exporting consumable code for users
• /src/types.ts - common TypeScript types that are used across the library
• /src/generate/index.ts - main function for generating data for release notes, utils.ts contains helper functions
• /src/format/index.ts - main function for formatting output, utils.ts contains helper functions
• /src/integrations/index.ts - exports an object containing configured integrations

Contributors: Adding a Configured Integration

1. Locate the folder /src/integrations
2. Within that folder:
   1. If adding a source control integration, locate the ./scm folder
   2. If adding a project management tool integration, locate the ./pmt folder
3. Add a new file with the name of the tool as the filename.
4. Implement the new integration, following the implementations of /src/integrations/scm/github.ts for SCM and /src/integrations/pmt/jira.ts for project management tools
5. In /src/integrations/index.ts, import the new integration and export it, following the pattern there.
6. Add a test (or multiple tests) in /src/__tests__/index.test.ts, to validate that it works as expected. Feel free to use the existing tests as a template.

Releases

Releases of this package are automatically published via GitHub actions to the GitHub Packages repository.