https://github.com/oscarotero/keep-a-changelog
Node & Deno package to parse and generate changelogs
https://github.com/oscarotero/keep-a-changelog
changelog changelog-generator deno keepachangelog node
Last synced: 16 days ago
JSON representation
Node & Deno package to parse and generate changelogs
- Host: GitHub
- URL: https://github.com/oscarotero/keep-a-changelog
- Owner: oscarotero
- License: mit
- Created: 2017-12-07T11:42:58.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-07-21T20:32:40.000Z (9 months ago)
- Last Synced: 2024-10-12T00:45:12.233Z (6 months ago)
- Topics: changelog, changelog-generator, deno, keepachangelog, node
- Language: TypeScript
- Homepage:
- Size: 164 KB
- Stars: 61
- Watchers: 5
- Forks: 20
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Changelog
[Keep a Changelog](https://github.com/oscarotero/keep-a-changelog) library for
Node & Deno
Deno package to parse and generate changelogs following the
[keepachangelog](https://keepachangelog.com/) format.
## Usage in Node
```js
import { parser } from "keep-a-changelog";
import fs from "fs";
//Parse a changelog file
const changelog = parser(fs.readFileSync("CHANGELOG.md", "UTF-8"));
//Generate the new changelog string
console.log(changelog.toString());
```
## Usage in Deno
```js
import { parser } from "https://deno.land/x/[email protected]/mod.ts";
//Parse a changelog file
const changelog = parser(await Deno.readTextFile("CHANGELOG.md"));
//Generate the new changelog string
console.log(changelog.toString());
```
### Create a new changelog
```js
import {
Changelog,
Release,
} from "https://deno.land/x/[email protected]/mod.ts";
const changelog = new Changelog("My project")
.addRelease(
new Release("0.1.0", "2017-12-06")
.added("New awesome feature")
.added("New other awesome feature")
.fixed("Bug #3")
.removed("Drop support for X"),
)
.addRelease(
new Release("0.2.0", "2017-12-09")
.security("Fixed security vulnerability")
.deprecated("Feature X is deprecated"),
);
console.log(changelog.toString());
```
### Custom output format
By default, the output format of the markdown is "compact", that removes the
space after the headings. You can change it to follow the
[`markdownlint`](https://github.com/DavidAnson/markdownlint) rules:
```js
const changelog = new Changelog();
changelog.format = "markdownlint";
```
### Custom bullet style
By default, the bullet style of the markdown is "-". You can change it to use
other styles of bullet points:
```js
const changelog = new Changelog();
changelog.bulletStyle = "*";
```
### Custom tag names
By default, the tag names are `v` + version number. For example, the tag for the
version `2.4.9` is `v2.4.9`. To change this behavior, set a new
`tagNameBuilder`:
```js
const changelog = new Changelog();
changelog.tagNameBuilder = (release) => `version-${release.version}`;
```
### Custom compare links
By default, compare links are build compliant with GitHub format. To change this
behavior, set a new `compareLinkBuilder`:
```js
const changelog = new Changelog();
changelog.url = "https://bitbucket.org/oscarotero/keep-a-changelog";
changelog.compareLinkBuilder = (previous, release) =>
`${this.url}/branches/compare/${release.version}%0D${previous.version}`;
```
### Custom Change Types
By default and according to the [keepachangelog](https://keepachangelog.com/)
format, the change types are `Added`, `Changed`, `Deprecated`, `Removed`,
`Fixed`, and `Security`.
In case you'd like add another type, you need to extend the `Release` class to
support new types. Additionally, you have to tell the `parser` that it should
create instances of your new extended `Release` in order to parse your changelog
correctly.
For example, we would like to add a type `Maintenance`. Extend the provided
`Release` class:
```js
class CustomRelease extends Release {
constructor(version, date, description) {
super(version, date, description);
// add whatever types you want - in lowercase
const newChangeTypes = [
["maintenance", []],
];
this.changes = new Map([...this.changes, ...newChangeTypes]);
}
// for convenience, add a new method to add change of type 'maintanance'
maintenance(change) {
return this.addChange("maintenance", change);
}
}
```
And once you want to use the parser:
```js
const releaseCreator = (ver, date, desc) => new CustomRelease(ver, date, desc);
const changelog = parser(changelogTextContent, { releaseCreator });
```
## Cli
This library provides the `changelog` command to normalize the changelog format.
It reads the CHANGELOG.md file and override it with the new format:
### Install the library as script
Deno:
```sh
deno install --global --allow-read --allow-write -fr --name changelog https://deno.land/x/changelog/bin.ts
```
Node:
```sh
npm install keep-a-changelog -g
```
Run the script:
```sh
changelog
```
To use other file name:
```sh
changelog --file=History.md
```
To generate an empty new CHANGELOG.md file:
```sh
changelog --init
```
You can release automatically the latest "Unreleased" version:
```sh
changelog --release
```
If your "Unreleased" section has no version, you can specify it as an argument:
```sh
changelog --release 2.0.0
```
Print the latest released version:
```sh
changelog --latest-release
> 2.0.0
```
Print the latest release:
```text
changelog --latest-release-full
## 2.6.1 - 2025-02-24
### Fixed
- NPM publishing [#55], [#56].
```
See available options:
```sh
changelog --help
```