Initial implementation

.editorconfig

@@ -0,0 +1,6 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8

.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "rust"
+      - "skip changelog"
+    groups:
+      rust-dependencies:
+        update-types:
+          - "minor"
+          - "patch"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "github actions"
+      - "skip changelog"

.github/workflows/check_changelog.yml

@@ -0,0 +1,20 @@
+name: Check Changelog
+
+on:
+  pull_request:
+    types: [opened, reopened, labeled, unlabeled, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  check-changelog:
+    runs-on: ubuntu-latest
+    if: (!contains(github.event.pull_request.labels.*.name, 'skip changelog'))
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Check that CHANGELOG is touched
+        run: |
+          git fetch origin ${{ github.base_ref }} --depth 1 && \
+          git diff remotes/origin/${{ github.base_ref }} --name-only | grep CHANGELOG.md

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+defaults:
+  run:
+    # Setting an explicit bash shell ensures GitHub Actions enables pipefail mode too,
+    # ratherthan only error on exit (improving failure UX when pipes are used). See:
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell
+    shell: bash
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Update Rust toolchain
+        run: rustup update
+
+      - name: Rust Cache
+        uses: Swatinem/[email protected]
+
+      - name: Clippy
+        run: cargo clippy --all-targets --all-features -- --deny warnings
+
+      - name: rustfmt
+        run: cargo fmt -- --check
+
+      - name: Check docs
+        run: RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Update Rust toolchain
+        run: rustup update
+
+      - name: Rust Cache
+        uses: Swatinem/[email protected]
+
+      - name: Test
+        run: cargo test --all-features

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Added serialization / deserialization of changelogs in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "keep_a_changelog"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.74"
+
+[dependencies]
+chrono = "0.4"
+indexmap = "2"
+lazy_static = "1"
+markdown = "1.0.0-alpha.14"
+regex = "1"
+semver = "1"
+thiserror = "1"
+uriparse = "0.6"
+
+[lints.rust]
+unused_crate_dependencies = "warn"
+unreachable_pub = "warn"
+unsafe_code = "warn"
+missing_docs = "warn"
+
+[lints.clippy]
+panic_in_result_fn = "warn"
+pedantic = "warn"
+unwrap_used = "warn"
+enum_variant_names = "allow"
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+module_name_repetitions = "allow"

LICENSE

@@ -1,21 +1,29 @@
-MIT License
+BSD 3-Clause License
 
-Copyright (c) 2023 Colin Casey
+Copyright (c) 2023, Salesforce.com, Inc.
+All rights reserved.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1 +1,59 @@
-# keep-a-changelog
+# Keep a Changelog Serializer/Deserializer
+
+[![Build Status]][ci] [![Docs]][docs.rs] [![Latest Version]][crates.io] [![MSRV]][install-rust]
+
+[Build Status]: https://img.shields.io/github/actions/workflow/status/heroku/libcnb.rs/ci.yml?branch=main
+[ci]: https://github.com/heroku/libcnb.rs/actions/workflows/ci.yml?query=branch%3Amain
+[Docs]: https://img.shields.io/docsrs/libcnb
+[docs.rs]: https://docs.rs/libcnb/latest/libcnb/
+[Latest Version]: https://img.shields.io/crates/v/libcnb.svg
+[crates.io]: https://crates.io/crates/libcnb
+[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.74+-lightgray.svg
+[install-rust]: https://www.rust-lang.org/tools/install
+
+A serializer and deserializer for changelogs written in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## Install
+
+```sh
+cargo add keep_a_changelog
+```
+
+## Usage
+
+```rust
+use keep_a_changelog::{Changelog, ChangeGroup, PromoteOptions};
+
+fn main() {
+    // parse a changelog
+    let mut changelog: Changelog = "\
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]"
+        .parse()
+        .unwrap();
+
+    // modify the unreleased section
+    changelog.unreleased.add(
+        ChangeGroup::Fixed, 
+        "Fixed bug in feature X"
+    );
+    changelog.unreleased.add(
+        ChangeGroup::Deprecated, 
+        "Feature Y will be removed from the next major release"
+    );
+
+    // promote the unreleased changes to a new release
+    let promote_options = PromoteOptions::new("0.0.1".parse().unwrap())
+        .with_link("https://github.com/my-org/my-project/releases/v0.0.1".parse().unwrap());
+    changelog.promote_unreleased(&promote_options).unwrap();
+
+    // output the changelog
+    println!("{}", changelog);
+}
+```

src/change_group.rs

@@ -0,0 +1,31 @@
+use std::fmt::{Display, Formatter};
+
+/// Changes in a release are grouped into one of several types.
+#[derive(Debug, Eq, PartialEq, Hash, Clone)]
+pub enum ChangeGroup {
+    /// For new features.
+    Added,
+    /// For changes in existing functionality.
+    Changed,
+    /// For soon-to-be removed features.
+    Deprecated,
+    /// For any bug fixes.
+    Fixed,
+    /// For new removed features.
+    Removed,
+    /// In case of vulnerabilities.
+    Security,
+}
+
+impl Display for ChangeGroup {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ChangeGroup::Added => write!(f, "Added"),
+            ChangeGroup::Changed => write!(f, "Changed"),
+            ChangeGroup::Deprecated => write!(f, "Deprecated"),
+            ChangeGroup::Removed => write!(f, "Removed"),
+            ChangeGroup::Fixed => write!(f, "Fixed"),
+            ChangeGroup::Security => write!(f, "Security"),
+        }
+    }
+}