Skip to content

Latest commit

 

History

History
246 lines (195 loc) · 8.65 KB

README.md

File metadata and controls

246 lines (195 loc) · 8.65 KB
Raw
changescribe logo
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

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.

CHANGELOG FORMAT VERSIONING

[1.0.0] - 2023-09-26

TASK

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]