# parse-changelog
This is a simplified changelog updater/parser, made for CI pipeline use. It has these abilities:
1. Add a new change to the changelog, in the Unreleased section
1. Add a new release into the changelog, using the list of changes from the Unreleased section
1. Parse the releases in the changelog into a JSON structure.

Changelogs must be in the format documented by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), see the details
below.

Release history: [parse-changelog's CHANGELOG](https://github.com/cseelye/parse-changelog/blob/main/CHANGELOG.md)

## Adding a Release
This mode is invoked by using the `--release` arg and will parse the changelog and insert a new release at the beginning
of the list of releases, using the changes from the Unreleased section. You can optionally specify a release date, or by
default use todays date.

The changelog must use the format `## [Unreleased]` (case insensitive) for this parser to find it.
For example, here is the diff generated by adding a new release(`--release 1.0.2`):
```
## [Unreleased]
+
+## [1.0.2] - 2022-10-20
 * Great new stuff

 ## [1.0.1] - 2022-10-08
```

## Adding a Change
This mode is invoked with the `--add-change` and `--type` args. It will parse the changelog to find the Unreleased
section and any changes already there, find the correct change type heading, and add the new change.
For example, here is the diff generated by adding a new fix (`--add-change "Fix that annoying bug" --type fixed`):
```
## [Unreleased]
 * Great new stuff
+### Fixed
+* Fix that annoying bug

 ## [1.0.1] - 2022-10-08
```

## Changelog Parsing
This mode will parse the changelog into JSON and print it to the screen. It finds all of
the heading2 entries (lines starting with `##`) and assumes each of those is a release. For each release, it parses
the release title into version and date, and collects the content of the release as a single string. Each release
heading must be of the format `## [release_version] - YYYY-MM-DD`, where `release_version` matches SemVer version string
spec, and `YYYY-MM-DD` is a valid year-month-day. The one exception to this format is the special release heading for
unreleased changes, which must match `## [Unreleased]`. The content of the release is parsed as a single string and not
interpreted in any way.

The top heading1 and project description are parsed into a special section named "introduction".

For example, given the following changelog:
```
# Changelog

My Project Name

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
* Great new stuff

## [1.0.1] - 2022-10-08
### Fixed
* Minor bug that we missed
### Changed
* New name for an artifact

## [1.0.0] - 2022-09-01
Initial release
* Some cool feature
* Other interesting stuff
```

It will be parsed into this JSON:

```
{
  "introduction": {
    "title": "Changelog",
    "content": "\nMy Project Name\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).",
    "version": "",
    "date": ""
  },
  "prerelease": {
    "title": "[Unreleased]",
    "content": "* Great new stuff",
    "version": "prerelease",
    "date": "unreleased"
  },
  "[1.0.1] - 2022-10-08": {
    "title": "[1.0.1] - 2022-10-08",
    "content": "### Fixed\n* Minor bug that we missed\n### Changed\n* New name for an artifact",
    "version": "1.0.1",
    "date": "2022-10-08"
  },
  "[1.0.0] - 2022-09-01": {
    "title": "[1.0.0] - 2022-09-01",
    "content": "Initial release\n* Some cool feature\n* Other interesting stuff",
    "version": "1.0.0",
    "date": "2022-09-01"
  }
}
```
