Conventional Changelog jQuery

Conventional Changelog jQuery is a preset configuration for conventional-changelog that follows the jQuery project's commit message convention. It provides parsing rules for commit messages with the format "Component: Short Description" and implements semantic version bumping logic based on jQuery's contribution guidelines.

Package Information

• Package Name: conventional-changelog-jquery
• Package Type: npm
• Language: JavaScript (ES Modules)
• Installation: npm install conventional-changelog-jquery
• Node Version: >=18

Core Imports

import createPreset from "conventional-changelog-jquery";

For dynamic imports:

const { default: createPreset } = await import("conventional-changelog-jquery");

Basic Usage

import conventionalChangelogCore from "conventional-changelog-core";
import createPreset from "conventional-changelog-jquery";

// Create the preset configuration
const preset = await createPreset();

// Use with conventional-changelog-core
for await (let chunk of conventionalChangelogCore({
  cwd: process.cwd(),
  config: preset
})) {
  console.log(chunk.toString());
}

Architecture

The conventional-changelog-jquery preset is built around three core components that work together within the conventional-changelog ecosystem:

• Parser Component: Extracts structured data from jQuery-formatted commit messages using regex pattern matching
• Writer Component: Transforms parsed commits into formatted changelog entries using Handlebars templates and custom transform logic
• Version Bump Component: Analyzes commit types and breaking change notes to determine appropriate semantic version increments
• Template System: Provides consistent formatting through separate Handlebars templates for headers, commits, and overall structure

The preset integrates seamlessly with conventional-changelog-core, which handles git history traversal and calls the appropriate preset methods during changelog generation. Each component can be configured independently while maintaining compatibility with jQuery's established commit message conventions.

jQuery Commit Message Format

The preset expects commits in jQuery's standardized format:

Component: Short Description

Optional Long Description

Fixes #xxx
Closes gh-yyy
Ref #zzz

Examples:

• Core: Make jQuery objects iterable
• Event: Remove an internal argument to the on method
• CSS: Don't name the anonymous swap function

Capabilities

Preset Creation

Creates a complete preset configuration object for conventional-changelog following jQuery's commit message conventions.

/**
 * Creates a jQuery preset configuration for conventional-changelog
 * @returns Promise<PresetConfig> - Complete preset configuration object
 */
function createPreset(): Promise<PresetConfig>;

interface PresetConfig {
  parser: ParserOptions;
  writer: WriterOptions;
  whatBump: WhatBumpFunction;
}

interface ParserOptions {
  headerPattern: RegExp;
  headerCorrespondence: string[];
}

interface WriterOptions {
  mainTemplate: string;
  headerPartial: string;
  commitPartial: string;
  transform: TransformFunction;
  groupBy: string;
  commitGroupsSort: string;
  commitsSort: string[];
}

type TransformFunction = (commit: CommitObject) => TransformedCommit | undefined;

type WhatBumpFunction = (commits: CommitObject[]) => BumpResult;

interface BumpResult {
  level: number; // 0=major, 1=minor, 2=patch
  reason: string; // Explanation of the bump decision
}

interface CommitObject {
  notes: BreakingChangeNote[];
  type?: string;
  component?: string;
  references?: ReferenceObject[];
  hash?: string;
  shortHash?: string;
  [key: string]: any;
}

interface BreakingChangeNote {
  title: string;
  text: string;
}

interface ReferenceObject {
  prefix: string;
  issue: string;
  owner?: string;
  repository?: string;
  originalIssueTracker?: string;
}

interface TransformedCommit {
  shortHash: string;
  references: ReferenceObject[];
}

The preset configuration includes:

Parser Configuration:

• Header Pattern: Uses regex /^(\w*): (.*)$/ to match jQuery commit format
• Field Mapping: Maps captures to component and shortDesc fields

Writer Configuration:

• Transform Function: Filters out commits without valid components and enhances valid commits with processed references and short hash
• Issue Reference Mapping: Maps # prefixed issues to jQuery bug tracker (https://bugs.jquery.com/ticket/)
• Component Grouping: Groups commits by component name in changelog
• Commit Sorting: Sorts by component, then by short description
• Template System: Uses Handlebars templates for consistent formatting

Version Bump Logic:

• Major (0): When commits contain breaking change notes
• Minor (1): When commits have type "feat" and no breaking changes
• Patch (2): Default for other commits

Template System

The preset includes three Handlebars templates:

Main Template

Structures the overall changelog layout with header and commit groups.

Header Template

Generates version headers with optional comparison links:

{{#if isPatch}}##{{else}}#{{/if}} {{version}}{{#if date}} ({{date}}){{/if}}

Commit Template

Formats individual commit entries with:

• Short description or full header
• Commit hash with optional link
• Issue references with proper jQuery bug tracker mapping

Issue Reference Handling

The preset handles multiple reference types:

• #xxx: Maps to jQuery bug tracker (https://bugs.jquery.com/ticket/xxx)
• gh-xxx: Maps to GitHub issues (https://github.com/owner/repo/issues/xxx)
• user/repo#xxx: Maps to external repository issues

Usage Examples:

Event: Fix delegation bug

Fixes #123, gh-456
Ref jquery/jquery-ui#789

Error Handling

The transform function filters out invalid commits:

• Commits without a component field are excluded from changelog
• Component must be a non-empty string
• This ensures only properly formatted jQuery commits appear in output

Integration Example

Complete example showing preset integration with conventional-changelog workflow:

import conventionalChangelogCore from "conventional-changelog-core";
import createPreset from "conventional-changelog-jquery";
import { promisify } from "util";
import { exec } from "child_process";

const execAsync = promisify(exec);

async function generateChangelog() {
  // Create preset
  const preset = await createPreset();
  
  // Generate changelog
  let changelog = '';
  for await (const chunk of conventionalChangelogCore({
    cwd: process.cwd(),
    config: preset
  })) {
    changelog += chunk.toString();
  }
  
  return changelog;
}

// Use in release workflow
const changelog = await generateChangelog();
console.log(changelog);