| | | :---------------------------------------: | | changescribe 𐫴 generated by AI |

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.

• Installation
  • 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)

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] | | --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] |