feat: add config for release description

UpHabit · Apr 7, 2020 · cd25e0d · cd25e0d
1 parent ea79f61
commit cd25e0d
Show file tree

Hide file tree

Showing 4 changed files with 115 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -41,33 +41,63 @@ Please note that `ticketRegex` cannot be used together with `ticketPrefixes`.
 ```
 ```typescript
 interface Config {
-
-  /// A domain of a jira instance ie: `uphabit.atlasian.net`
+  /**
+   * A domain of a jira instance ie: `uphabit.atlasian.net`
+   */
   jiraHost: string;
 
-  // A list of prefixes to match when looking for tickets in commits. Cannot be used together with ticketRegex.
-  // ie. ['TEST'] would match `TEST-123` and `TEST-456`
+  /**
+   * A list of prefixes to match when looking for tickets in commits. Cannot be used together with ticketRegex.
+   *
+   * ie. ['TEST'] would match `TEST-123` and `TEST-456`
+   */
   ticketPrefixes?: string[];
 
-  // A unescaped regex to match tickets in commits (without slashes). Cannot be used together with ticketPrefixes.
-  // ie. [a-zA-Z]{4}-\d{3,5} would match any ticket with 3 letters a dash and 3 to 5 numbers, such as `TEST-456`, `TEST-5643` and `TEST-56432`
+  /**
+   * A unescaped regex to match tickets in commits (without slashes). Cannot be used together with ticketPrefixes.
+   *
+   * ie. [a-zA-Z]{4}-\d{3,5} would match any ticket with 3 letters a dash and 3 to 5 numbers, such as `TEST-456`, `TEST-5643` and `TEST-56432`
+   */
   ticketRegex?: string;
-
-  // The id or key for the project releases will be created in
+
+  /**
+   * The id or key for the project releases will be created in
+   */
   projectId: string;
-
-  // A lodash template with a single `version` variable
-  // defaults to `v${version}` which results in a version that is named like `v1.0.0`
-  // ex: `Semantic Release v${version}` results in `Semantic Release v1.0.0`
+
+  /**
+   * A lodash template with a single `version` variable
+   * defaults to `v${version}` which results in a version that is named like `v1.0.0`
+   * ex: `Semantic Release v${version}` results in `Semantic Release v1.0.0`
+   *
+   * @default `v${version}`
+   */
   releaseNameTemplate?: string;
 
-  // The number of maximum parallel network calls, default 10
+  /**
+   * A lodash template for the release.description field
+   *
+   * template variables:
+   *    version: the sem-ver version ex.: 1.2.3
+   *      notes: The full release notes: This may be very large
+   *             Only use it if you have very small releases
+   *
+   * @default `Automated released with semantic-release-jira-releases https://git.io/JvAbj`
+   */
+  releaseDescriptionTemplate?: string;
+
+  /**
+   * The number of maximum parallel network calls, default 10
+   */
   networkConcurrency?: number;
 
-  // indicates if a new release created in jira should be set as released
+  /**
+   * indicates if a new release created in jira should be set as released
+   */
   released?: boolean;
-  // include the release date when creating a release in jira
+  /**
+   * include the release date when creating a release in jira
+   */
   setReleaseDate?: boolean;
-
 }
 ```
diff --git a/lib/success.ts b/lib/success.ts
@@ -3,7 +3,7 @@ import * as _ from 'lodash';
 import pLimit from 'p-limit';
 
 import { makeClient } from './jira';
-import { GenerateNotesContext, PluginConfig } from './types';
+import { DEFAULT_RELEASE_DESCRIPTION_TEMPLATE, DEFAULT_VERSION_TEMPLATE, GenerateNotesContext, PluginConfig } from './types';
 import { escapeRegExp } from './util';
 
 export function getTickets(config: PluginConfig, context: GenerateNotesContext): string[] {
@@ -32,7 +32,7 @@ export function getTickets(config: PluginConfig, context: GenerateNotesContext):
   return [...tickets];
 }
 
-async function findOrCreateVersion(config: PluginConfig, context: GenerateNotesContext, jira: JiraClient, projectIdOrKey: string, name: string): Promise<Version> {
+async function findOrCreateVersion(config: PluginConfig, context: GenerateNotesContext, jira: JiraClient, projectIdOrKey: string, name: string, description: string): Promise<Version> {
   const remoteVersions = await jira.project.getVersions({ projectIdOrKey });
   context.logger.info(`Looking for version with name '${name}'`);
   const existing = _.find(remoteVersions, { name });
@@ -51,10 +51,11 @@ async function findOrCreateVersion(config: PluginConfig, context: GenerateNotesC
       id: 'dry_run_id',
     } as any;
   } else {
+    const descriptionText = description || '';
     newVersion = await jira.version.createVersion({
       name,
       projectId: projectIdOrKey as any,
-      description: context.nextRelease.notes,
+      description: descriptionText,
       released: Boolean(config.released),
       releaseDate: config.setReleaseDate ? (new Date().toISOString()) : undefined,
     });
@@ -103,15 +104,18 @@ export async function success(config: PluginConfig, context: GenerateNotesContex
 
   context.logger.info(`Found ticket ${tickets.join(', ')}`);
 
-  const template = _.template(config.releaseNameTemplate || 'v${version}');
-  const newVersionName = template({ version: context.nextRelease.version });
+  const versionTemplate = _.template(config.releaseNameTemplate ?? DEFAULT_VERSION_TEMPLATE);
+  const newVersionName = versionTemplate({ version: context.nextRelease.version });
+
+  const descriptionTemplate = _.template(config.releaseDescriptionTemplate ?? DEFAULT_RELEASE_DESCRIPTION_TEMPLATE);
+  const newVersionDescription = descriptionTemplate({ version: context.nextRelease.version, notes: context.nextRelease.notes });
 
   context.logger.info(`Using jira release '${newVersionName}'`);
 
   const jira = makeClient(config, context);
 
   const project = await jira.project.getProject({ projectIdOrKey: config.projectId });
-  const releaseVersion = await findOrCreateVersion(config, context, jira, project.id, newVersionName);
+  const releaseVersion = await findOrCreateVersion(config, context, jira, project.id, newVersionName, newVersionDescription);
 
   const concurrentLimit = pLimit(config.networkConcurrency || 10);
 

diff --git a/lib/types.ts b/lib/types.ts
@@ -55,14 +55,66 @@ export interface BaseConfig {
   dryRun: boolean;
 }
 
+export const DEFAULT_VERSION_TEMPLATE = 'v${version}';
+export const DEFAULT_RELEASE_DESCRIPTION_TEMPLATE = 'Automated release with semantic-release-jira-releases https://git.io/JvAbj';
+
 export interface PluginConfig extends BaseConfig {
+  /**
+   * A domain of a jira instance ie: `uphabit.atlasian.net`
+   */
+  jiraHost: string;
+
+  /**
+   * A list of prefixes to match when looking for tickets in commits. Cannot be used together with ticketRegex.
+   *
+   * ie. ['TEST'] would match `TEST-123` and `TEST-456`
+   */
   ticketPrefixes?: string[];
+
+  /**
+   * A unescaped regex to match tickets in commits (without slashes). Cannot be used together with ticketPrefixes.
+   *
+   * ie. [a-zA-Z]{4}-\d{3,5} would match any ticket with 3 letters a dash and 3 to 5 numbers, such as `TEST-456`, `TEST-5643` and `TEST-56432`
+   */
   ticketRegex?: string;
+
+  /**
+   * The id or key for the project releases will be created in
+   */
   projectId: string;
+
+  /**
+   * A lodash template with a single `version` variable
+   * defaults to `v${version}` which results in a version that is named like `v1.0.0`
+   * ex: `Semantic Release v${version}` results in `Semantic Release v1.0.0`
+   *
+   * @default `v${version}`
+   */
   releaseNameTemplate?: string;
-  jiraHost: string;
+
+  /**
+   * A lodash template for the release.description field
+   *
+   * template variables:
+   *    version: the sem-ver version ex.: 1.2.3
+   *      notes: The full release notes: This may be very large
+   *             Only use it if you have very small releases
+   *
+   * @default `Automated release with semantic-release-jira-releases https://git.io/JvAbj`
+   */
+  releaseDescriptionTemplate?: string;
+
+  /**
+   * The number of maximum parallel network calls, default 10
+   */
   networkConcurrency?: number;
 
+  /**
+   * indicates if a new release created in jira should be set as released
+   */
   released?: boolean;
+  /**
+   * include the release date when creating a release in jira
+   */
   setReleaseDate?: boolean;
 }
diff --git a/lib/verifyConditions.ts b/lib/verifyConditions.ts
@@ -42,6 +42,12 @@ export async function verifyConditions(config: PluginConfig, context: PluginCont
     }
   }
 
+  if (config.releaseDescriptionTemplate !== null || config.releaseDescriptionTemplate !== undefined) {
+    if (typeof config.releaseDescriptionTemplate !== 'string') {
+      throw new SemanticReleaseError('config.releaseDescriptionTemplate must be a string');
+    }
+  }
+
   if (networkConcurrency && (typeof networkConcurrency !== 'number' || networkConcurrency < 1)) {
     throw new SemanticReleaseError(`config.networkConcurrency must be an number greater than 0`);
   }