changescribe

A CHANGELOG.md utility generator. Provide a folder /unreleased with a Markdown file for each of your completed tasks: each file should be named with the task or ticket code related.

Run this utility in order to generate or update a CHANGELOG file merging each file in a new release or explore a range of versions included in the CHANGELOG. You must specify the semver version code for the next release to be generated.

• changescribe
  • Installation
    • Configuration
    • Issue Tracking System Integration
      • Simple Configuration (Recommended)
      • Advanced Configuration
  • Commands and usage
    • Generate (default)
      • Task file format
        • Example
    • Explore
    • Init

Installation

This tool needs NodeJS and it is tested with node version 16 ~ 20.X.

npm install -g @ctinnovation/changescribe
changescribe --help

Configuration

You can configure this utility by using the inline CLI arguments illustrated below (EG: --targetVersion 1.1.0) or by creating a file .changescriberc in the root path you will run this tool into.

When using a .changescriberc file (default JSON or alternately CommonJS using extension .js or .cjs) you can specify the default values to use for each available command:

{
  "generate": {
    "fromPackageJson": true,
    "targetVersion": "1.1.1"
  },
  "init": {
    "output": "/test/CHANGELOG.md"
  },
  "explore": {
    "output": "console"
  }
}

Once you run changescribe the arguments defaults will be resolved in this order of priority:

1. Command defaults (the defaults value illustrated by executing changescribe --help)
2. .changescriberc(.c?js)? values, if the file exists
3. Inline CLI arguments passed (EG: changescribe --targetVersion 1.1.0)

Issue Tracking System Integration

Changescribe supports automatic link generation to your issue tracking system (GitHub, GitLab, Jira, etc.).

Simple Configuration (Recommended)

Use the issueSystem parameter to automatically configure the pattern for extracting project and issue information.

GitHub Issues - Simplest (with projectName):

{
  "generate": {
    "fromPackageJson": true,
    "issueSystem": "github",
    "projectName": "my-app",
    "taskUrlTemplate": "https://github.com/your-org/{project}/issues/{taskCode}"
  }
}

File naming: Just the issue number! 42.md, 123.md

• Uses projectName from config: project = my-app
• Uses filename as issue number: issue = 42
• Generates link: https://github.com/your-org/my-app/issues/42

GitHub Issues - Alternative (without projectName):

{
  "generate": {
    "fromPackageJson": true,
    "issueSystem": "github",
    "taskUrlTemplate": "https://github.com/your-org/{project}/issues/{taskCode}"
  }
}

File naming: projectname-123.md (e.g., my-app-42.md)

• Automatically extracts: project = my-app, issue = 42
• Generates link: https://github.com/your-org/my-app/issues/42

Jira Issues:

{
  "generate": {
    "fromPackageJson": true,
    "issueSystem": "jira",
    "taskUrlTemplate": "https://yourdomain.atlassian.net/browse/{taskCode}"
  }
}

File naming: PROJ-123.md

• Uses full filename: taskCode = PROJ-123
• Generates link: https://yourdomain.atlassian.net/browse/PROJ-123

GitLab Issues:

{
  "generate": {
    "fromPackageJson": true,
    "issueSystem": "gitlab",
    "taskUrlTemplate": "https://gitlab.com/your-org/{project}/-/issues/{taskCode}"
  }
}

File naming: projectname-456.md

• Automatically extracts: project = projectname, issue = 456
• Generates link: https://gitlab.com/your-org/projectname/-/issues/456

Advanced Configuration

For custom patterns, use taskCodePattern with a regex:

{
  "generate": {
    "taskCodePattern": "^([A-Z]+-\\d+)",
    "taskUrlTemplate": "https://example.com/issue/{taskCode}"
  }
}

Note: taskCodePattern overrides issueSystem if both are specified.

Commands and usage

Generate (default)

In your unreleased folder you have a PR-120.md file with this content:

## Added 
- I added this

## Changed

- I've changed this
- And also this�

## Fixed

- I fixed this
- But also this!

Running this utility:

changescribe --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} --targetVersion 1.0.0

or

changescribe generate --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} --targetVersion 1.0.0

or (use package.json version as target version)

changescribe generate --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} -p

You'll have a CHANGELOG.md like this:

---

Changelog

All notable changes to this project will be documented in this file.

• [1.0.0] - 2023-09-26

[1.0.0] - 2023-09-26

Added

• I added this

Changed

• I've changed this
• And also this�

Fixed

• I fixed this
• But also this!

---

Feel free to customize your template by modifying the templates inside templates folder.

Argument	Description	Value
-t, --targetVersion	Specific target version. Mandatory if no --fromPackageJson specified	[string]
-p, --fromPackageJson	Retrieve target version from pkg.json (overrides --targetVersion)	[boolean] [default: false]
-o, --output	Ouput CHANGELOG file	[string] [default: process.pwd()/CHANGELOG.md]
-i, --input	Input folder for compiling the changelog	[string] [default: process.pwd()/unreleased]
-u, --taskUrlTemplate	Associated task URL template. Mandatory if --excludeTaskList is false	[string] [required]
--issueSystem	Issue tracking system: "github", "gitlab", or "jira" (auto-configures pattern)	[string]
--projectName	Project name for GitHub/GitLab (allows using just issue numbers as filenames)	[string]
--taskCodePattern	Regex pattern to extract task code from filename (advanced, overrides issueSystem)	[string]
--excludeTaskList	Exclude tasks list after release title	[boolean] [default: false]
--createOutputIfNotFound	Create a new output file if not found	[boolean] [default: true]
--version	Show version number	[boolean]
--help	Show help	[boolean]

Task file format

For the generate command you must provide a Markdown file for each of yours task completed on the current branch. Each file:

• Should be named with the code of the task
• Should be splitted in sections with these titles:
  • If anything changed:
    • ## Change[d]
    • ## Edit[ed]
    • ## Update[d]
  • If anything was fixed/hotfixed:
    • ## [hot]Fix[ed]
  • If anything was added:
    • ## Add[ed]
    • ## Create[d]
  • If anything was removed:
    • ## Remove[d]
    • ## Cancel[led]
  • If anything was refactored
    • ## Refactor[ed]

The [notation] used here indicates optional group of characters inside the section title. Each possible variation will be standardised to the form: Changed, Added, Removed, Fixed

• Each section should list each change prepended with -.
  • If anything in your list is a breaking change you can prepend your list with [breaking]

🔥 The CHANGELOG format inspires to keepachangelog

Example

## Changed
- change 1
- change 2
- [breaking] breaking change 3!

## Fix
- fix 1
- fix 2

Explore

With changescribe explore can explore a range of versions contained in a CHANGELOG.md file generated with changescribe:

changescribe explore --range 1.2.1

This command will exctract you a range of versions, in this case from 1.2.1 to the latest. You'll get a console log similar to the following:

---

packageName changelog from 1.2.1 to 1.3.1 (1.2.1~1.3.1)

All notable changes to this project from version 1.2.1 to 1.3.1.

CHANGELOG FORMAT https://keepachangelog.com/en/1.0.0/

VERSIONING https://semver.org/spec/v2.0.0.html

1.3.1

https://jira.com/browse/{taskCode}

Added

• I added this

1.2.5

https://jira.com/browse/{taskCode}

Added

• I changed this

Fixed

• I fixed this

1.2.1

https://jira.com/browse/{taskCode}

Added

• I changed this

Fixed

• I fixed this

---

Argument	Description	Value
--version	Show version number	[boolean]
-r, --range	Range of versions in a format like X.Y.Z ~ A.B.C	[string] [required]
-o, --output	Output path. If not console you can specify a path which the resulting Markdown will be saved into	[string] [default: "console"]
-i, --input	Input CHANGELOG for explore diffs	[string] [default:process.pwd()/CHANGELOG.md]
--help	Show help	[boolean]

Init

Creates a new empty CHANGELOG.md file.

changescribe init

Argument	Description	Value
--version	Show version number	[boolean]
-o, --output	Ouput CHANGELOG file	[string] [default:process.pwd()/CHANGELOG.md]
--help	Show help	[boolean]