Skip to main content

Changelog Manager: Usage

A specialized CLI tool (@runespoor/changelog-manager) designed for managing changelogs and semantic versioning in single repositories, particularly optimized for Continuous Integration and Trunk Based Development workflows.

Core Commands

  1. rune change

    • Interactive command to document changes before merging
    • Generates timestamped JSON files containing change details
    • Captures change type (major/minor/patch/none), description, and optional issue links
  2. rune verify

    • CI-focused validation command
    • Ensures proper change files exist and are valid
    • Verifies branch differences and file naming conventions
  3. rune apply

    • Processes accumulated change files
    • Automatically bumps version numbers based on change types
    • Updates CHANGELOG.md and package.json
    • Commits and pushes changelogs

Key Features

  • Automated Version Management: Intelligently handles semantic versioning based on change types
  • Standardized Change Documentation: Enforces consistent changelog formats
  • CI/CD Integration: Built-in commands for verification in CI pipelines
  • Issue Tracking: Optional integration with issue tracking systems
  • Git Integration: Automated commit and push functionality

Use Cases

  • Maintaining consistent changelog entries across team members
  • Automating version bumps based on change significance
  • Enforcing change documentation in CI/CD pipelines
  • Tracking changes with associated issue references
  • Standardizing release documentation

The tool essentially automates the often manual and error-prone process of maintaining changelogs and version numbers in a development workflow.

Install

npm install --save-dev @runespoorstack/changelog-manager

Setup

Add npm scripts to your package.json file.

{
...
"scripts": {
...
"changelog:change": "rune change --issueLinkPattern https://jira.com/browse/{{issueId}}",
"changelog:verify": "rune verify",
"changelog:apply": "rune apply"
}
...
}

Integrate rune verify command with your Merge Request CI (GitHub Actions example). Make sure to add this job on the beginning of your pipeline:

name: Merge Request CI
on:
pull_request:
branches:
- '*'

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

jobs:
changelog-verify:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout Repository
uses: actions/checkout@v4

- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'

- name: Install dependencies
run: npm ci

- name: Verify Changelog
run: npm run changelog:verify -- --sourceBranch origin/${{ github.head_ref || github.ref_name }} -- --remoteName origin

...

Integrate rune apply command with your Main CI (GitHub Actions example). Authorize the git user and personal access token as a secret to be able to push to the repository. Read the Guide I suggest creating the separate service account for such purposes. Make sure to add this job to the end of your pipeline:

name: Main CI
on:
push:
branches:
- main

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.ref == 'refs/heads/main' }}


jobs:

...

changelog-apply:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 2
token: ${{ secrets.ACTIONS_PTA }}

- name: Git set author name
run: git config --global user.name "ServiceAccount"

- name: Git set author email
run: git config --global user.email "serviceaccount@gmail.com"

- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'

- name: Install dependencies
run: npm ci

- name: Apply Changelog
run: npm run changelog:apply

Manual commands

Run rune change command and commit the resulted files to provide change files, before opening any Merge Request:

npm run changelog:change