@runespoorstack/changelog-manager

The Runespoor CLI for changelog management and semantic versioning.

Table of Contents

• Table of Contents
• Core Commands
• Key Features
• Use Cases
• Usage
  • Install
  • Setup
  • Manual commands
• 🛠️ Contributing
• 💕 Special Thanks
• ❤️ Support or Donate

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, author, 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
• Multi Changelogs: Ability to keep separate changelogs for separate purposes.

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.

Usage

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 "[email protected]"

    - 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

For more information, read the technical documentation.

🛠️ Contributing

See the CONTRIBUTING.md document.

💕 Special Thanks

• I want to say thank you to the best woman in the world, my wife Diana for her love, daily support, motivation and inspiration.

❤️ Support or Donate

If you are enjoying this work and feel extra appreciative, you could buy me a book 📖 or 3 📖📖📖.