#changelog #parser

bin+lib parse-changelog

A simple changelog parser, written in Rust

9 unstable releases (3 breaking)

new 0.4.3 Jul 24, 2021
0.4.2 Jul 22, 2021
0.3.0 Apr 12, 2021
0.2.2 Jan 5, 2021
0.1.0 Nov 29, 2020

#116 in Parser implementations

Download history 9/week @ 2021-04-05 30/week @ 2021-04-12 42/week @ 2021-04-19 35/week @ 2021-04-26 24/week @ 2021-05-03 26/week @ 2021-05-10 40/week @ 2021-05-17 1/week @ 2021-05-31 5/week @ 2021-06-07 1/week @ 2021-06-14 4/week @ 2021-06-21 13/week @ 2021-06-28 10/week @ 2021-07-05 15/week @ 2021-07-12 66/week @ 2021-07-19

77 downloads per month

Apache-2.0 OR MIT

305KB
588 lines

parse-changelog

crates.io docs.rs license rustc build status

A simple changelog parser, written in Rust.

Installation

CLI

From source

cargo install parse-changelog

From prebuilt binaries

You can download prebuilt binaries from the Release page. Prebuilt binaries are available for macOS, Linux (gnu and musl), and Windows.

Via Homebrew

You can install parse-changelog using Homebrew tap on macOS and Linux:

brew install taiki-e/tap/parse-changelog

Library

To use this crate as a library, add this to your Cargo.toml:

[dependencies]
parse-changelog = { version = "0.4", default-features = false }

Note: When using this crate as a library, we recommend disabling the default features because the default features enable CLI-related dependencies and the library part of this crate does not use them.

Compiler support: requires rustc 1.51+

Usage (CLI)

parse-changelog command parses changelog and returns a release note for the specified version.

Click to show a complete list of options
$ parse-changelog --help
parse-changelog
Parses changelog and returns a release note for the specified version

USAGE:
    parse-changelog [OPTIONS] <PATH> [VERSION]

OPTIONS:
    -t, --title
            Returns title instead of notes

        --json
            Returns JSON representation of all releases in changelog

        --version-format <PATTERN>
            Specify version format

        --prefix <PATTERN>
            Alias for --prefix-format

        --prefix-format <PATTERN>
            Specify prefix format

    -h, --help
            Prints help information

    -V, --version
            Prints version information


ARGS:
    <PATH>
            Path to the changelog file (use '-' for standard input)

    <VERSION>
            Specify version (by default, select the latest release)

Example: Get Rust's release notes

Get the release note for version 1.46.0 from Rust's release notes:

curl -sSf https://raw.githubusercontent.com/rust-lang/rust/master/RELEASES.md \
  | parse-changelog - 1.46.0

output of the above command.

Example: Get Cargo's changelog

In Cargo's changelog, the title starts with "Cargo ", and the patch version is omitted. This is a format parse-changelog don't support by default, so use --prefix and --version-format to specify a custom format. For example:

curl -sSf https://raw.githubusercontent.com/rust-lang/cargo/master/CHANGELOG.md \
  | parse-changelog --prefix 'Cargo ' --version-format '^\d+\.\d+$' - 1.50

output of the above command.

--prefix is the same as Parser::prefix_format and --version-format is the same as Parser::version_format. See documentation of those methods for more information.

Example: Create a new GitHub release from changelog

With GitHub CLI:

tag=...
version=...

# Get notes for $version from CHANGELOG.md.
notes=$(parse-changelog CHANGELOG.md "$version")
# Create a new GitHub release with GitHub CLI.
gh release create "$tag" --title "$version" --notes "$notes"

With softprops/action-gh-release GitHub Action:

name: Release

on:
  push:
    tags:
      - v[0-9]+.*

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Install parse-changelog
        run: cargo install parse-changelog
      - name: Generate Changelog
        run: |
          # Get version from github ref (remove 'refs/tags/' and prefix 'v')
          version="${GITHUB_REF#refs/tags/v}"
          # Get notes for $version from CHANGELOG.md.
          parse-changelog CHANGELOG.md "$version" > ${{ github.workflow }}-CHANGELOG.txt
      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: ${{ github.workflow }}-CHANGELOG.txt
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Usage (Library)

let changelog = "\
## 0.1.2 - 2020-03-01

- Bug fixes.

## 0.1.1 - 2020-02-01

- Added `Foo`.
- Added `Bar`.

## 0.1.0 - 2020-01-01

Initial release
";

// Parse changelog.
let changelog = parse_changelog::parse(changelog).unwrap();

// Get the latest release.
assert_eq!(changelog[0].version, "0.1.2");
assert_eq!(changelog[0].title, "0.1.2 - 2020-03-01");
assert_eq!(changelog[0].notes, "- Bug fixes.");

// Get the specified release.
assert_eq!(changelog["0.1.0"].title, "0.1.0 - 2020-01-01");
assert_eq!(changelog["0.1.0"].notes, "Initial release");
assert_eq!(changelog["0.1.1"].title, "0.1.1 - 2020-02-01");
assert_eq!(
    changelog["0.1.1"].notes,
    "- Added `Foo`.\n\
     - Added `Bar`."
);

See documentation for more information on parse-changelog as a library.

Supported Format

By default, this crate is intended to support markdown-based changelogs that have the title of each release starts with the version format based on Semantic Versioning. (e.g., Keep a Changelog's changelog format.)

Headings

The heading for each release must be Atx-style (1-6 #) or Setext-style (= or - in a line under text), and the heading levels must match with other releases.

Atx-style headings:

# 0.1.0
## 0.1.0

Setext-style headings:

0.1.0
=====
0.1.0
-----

Titles

The title of each release must start with a text or a link text (text with [ and ]) that starts with a valid version format. For example:

# [0.2.0]

description...

# 0.1.0

description...

You can also include characters before the version as prefix.

## Version 0.1.0
   ^^^^^^^^

By default only "v", "Version " and "Release " are allowed as prefixes and can be customized using the Parser::prefix_format method (--prefix-format option if command line).

You can freely include characters after the version (this crate does not parse it).

# 0.1.0 - 2020-01-01
       ^^^^^^^^^^^^^

Versions

## v0.1.0 -- 2020-01-01
    ^^^^^

The default version format is MAJOR.MINOR.PATCH(-PRE_RELEASE)?(+BUILD_METADATA)?, and is based on Semantic Versioning. (Pre-release version and build metadata are optional.)

This is parsed using the following regular expression:

^\d+\.\d+\.\d+(-[\w\.-]+)?(\+[\w\.-]+)?$

To customize the version format, use the Parser::version_format method (--version-format option if command line).

Related Projects

  • create-gh-release-action: GitHub Action for creating GitHub Releases based on changelog. (Using this crate for changelog parsing.)

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~4–5.5MB
~114K SLoC