docs: expand README example, tidy docs

ungoldman · ungoldman · commit 01659c725e5f · 2026-06-14T12:01:22.000-07:00
- README: example and output cover every visible parser case (verified)
- CHANGELOG: simplify preamble
- CONTRIBUTING: rewrite (code of conduct, contribution types)
- LICENSE: extend copyright year
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,6 @@
 # Change Log
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](http://keepachangelog.com/)
-and this project adheres to [Semantic Versioning](http://semver.org/).
+All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [3.0.1](https://github.com/ungoldman/changelog-parser/compare/v3.0.0...v3.0.1) - 2022-12-23
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,50 +1,23 @@
 # Contributing Guidelines
 
-Contributions welcome! Please check past issues and pull requests before you open your own issue or pull request to avoid duplicating a frequently asked question.
+## Code of Conduct
 
-In addition to improving the project, refactoring code, and implementing features, this project welcomes the following types of contributions:
+This project is intended to be a safe, welcoming space for collaboration.
 
-- **Ideas**: participate in an issue thread or start your own to have your voice heard.
-- **Writing**: contribute your expertise in an area by helping expand the included content.
-- **Copy editing**: fix typos, clarify language, and generally improve the quality of the content.
-- **Formatting**: help keep content easy to read with consistent formatting.
-
-## Install
-
-Fork and clone the repo, then `npm install` to install all dependencies.
-
-## Testing
-
-Tests are run with `npm test`. Please ensure all tests are passing before submitting a pull request (unless you're creating a failing test to increase test coverage or show a problem).
-
-## Code Style
-
-This repository uses [Biome](https://biomejs.dev/) for linting and formatting. `npm test` runs the linter, and `npm run format` applies fixes and formatting for you.
+All contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
----
+Thank you for being kind to each other!
 
-# Collaborating Guidelines
+## Contributions welcome!
 
-**This is an OPEN Open Source Project.**
+**Before spending lots of time on something, ask for feedback on your idea first!**
 
-## What?
+Please search [issues](../../issues/) and [pull requests](../../pulls/) before adding something new! This helps avoid duplicating efforts and conversations.
 
-Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
+This project welcomes any kind of contribution! Here are a few suggestions:
 
-## Rules
-
-There are a few basic ground-rules for contributors:
-
-1. **No `--force` pushes** or modifying the Git history in any way.
-1. **Non-master branches** ought to be used for ongoing work.
-1. **External API changes and significant modifications** ought to be subject to an **internal pull-request** to solicit feedback from other contributors.
-1. Internal pull-requests to solicit feedback are *encouraged* for any other non-trivial contribution but left to the discretion of the contributor.
-1. Contributors should attempt to adhere to the prevailing code style.
-
-## Releases
-
-Declaring formal releases remains the prerogative of the project maintainer.
-
-## Changes to this arrangement
-
-This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change.
+- **Ideas**: participate in an issue thread or start your own to have your voice heard.
+- **Writing**: contribute your expertise in an area by helping expand the included content.
+- **Copy editing**: fix typos, clarify language, and generally improve the quality of the content.
+- **Formatting**: help keep content easy to read with consistent formatting.
+- **Code**: help maintain and improve the project codebase.
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,6 +1,6 @@
 # [ISC License](https://spdx.org/licenses/ISC)
 
-Copyright (c) 2016, Nate Goldman <ungoldman@gmail.com>
+Copyright (c) 2016-2026, Nate Goldman <ungoldman@gmail.com>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
diff --git a/README.md b/README.md
@@ -128,122 +128,131 @@ Alternately you can run it without arguments and it will look for a `CHANGELOG.m
 This module assumes your change log is a [markdown](http://daringfireball.net/projects/markdown/syntax) file structured roughly like so:
 
 ```markdown
-# changelog title
+# Changelog
 
-A cool description (optional).
+All notable changes to this project are documented in this file.
 
-## unreleased
-* foo
+## Unreleased
 
-## x.y.z - YYYY-MM-DD (or DD.MM.YYYY, D/M/YY, etc.)
-* bar
+* Work in progress.
 
-## [a.b.c]
+## 2.2.0-beta.1 - 2024-03-20
 
-### Changes
+* Pre-release builds get a version too.
 
-* Update API
-* Fix bug #1
+## [2.1.0] - 2024-03-15
 
-## 2.2.3-pre.1 - 2013-02-14
-* Update API
+### Added
 
-## 2.0.0-x.7.z.92 - 2013-02-14
-* bark bark
-* woof
-* arf
+* A `format` option, documented in [the README](https://example.com).
+* Support for **bold** entries.
 
-## v1.3.0
+### Fixed
 
-* make it so
+- A crash on empty input.
 
-## [1.2.3](link)
-* init
+## 2.0.0 (2024-01-02)
 
-[a.b.c]: http://altavista.com
+* Drop support for Node 12.
+
+# 1.5.0 - 02.11.2023
+
+* An older entry under an H1 heading with a `DD.MM.YYYY` date.
+
+## v1.0.0
+
+* First stable release.
+
+## [0.9.0](https://example.com/releases/0.9.0)
+
+* Initial public prototype.
+
+[2.1.0]: https://example.com/releases/2.1.0
 ```
 
 Parsing the above example will return the following object:
 
 ```js
 {
-  title: 'changelog title',
-  description: 'A cool description (optional).',
+  title: 'Changelog',
+  description: 'All notable changes to this project are documented in this file.',
   versions: [
     { version: null,
-      title: 'unreleased',
+      title: 'Unreleased',
       date: null,
-      body: '* foo',
+      body: '* Work in progress.',
       parsed: {
         _: [
-          'foo'
+          'Work in progress.'
         ]
       }
     },
-    { version: 'x.y.z',
-      title: 'x.y.z - YYYY-MM-DD',
-      date: null,
-      body: '* bar',
+    { version: '2.2.0-beta.1',
+      title: '2.2.0-beta.1 - 2024-03-20',
+      date: '2024-03-20',
+      body: '* Pre-release builds get a version too.',
       parsed: {
         _: [
-          'bar'
+          'Pre-release builds get a version too.'
         ]
       }
     },
-    { version: 'a.b.c',
-      title: '[a.b.c]',
-      date: null,
-      body: '### Changes\n\n* Update API\n* Fix bug #1',
+    { version: '2.1.0',
+      title: '[2.1.0] - 2024-03-15',
+      date: '2024-03-15',
+      body: '### Added\n\n* A `format` option, documented in [the README](https://example.com).\n* Support for **bold** entries.\n\n### Fixed\n\n- A crash on empty input.',
       parsed: {
         _: [
-          'Update API',
-          'Fix bug #1'
+          'A format option, documented in the README.',
+          'Support for bold entries.',
+          'A crash on empty input.'
         ],
-        Changes: [
-          'Update API',
-          'Fix bug #1'
+        Added: [
+          'A format option, documented in the README.',
+          'Support for bold entries.'
+        ],
+        Fixed: [
+          'A crash on empty input.'
         ]
       }
     },
-    { version: '2.2.3-pre.1',
-      title: '2.2.3-pre.1 - 2013-02-14',
-      date: '2013-02-14',
-      body: '* Update API',
+    { version: '2.0.0',
+      title: '2.0.0 (2024-01-02)',
+      date: '2024-01-02',
+      body: '* Drop support for Node 12.',
       parsed: {
         _: [
-          'Update API'
+          'Drop support for Node 12.'
         ]
       }
     },
-    { version: '2.0.0-x.7.z.92',
-      title: '2.0.0-x.7.z.92 - 2013-02-14',
-      date: '2013-02-14',
-      body: '* bark bark\n* woof\n* arf',
+    { version: '1.5.0',
+      title: '1.5.0 - 02.11.2023',
+      date: '02.11.2023',
+      body: '* An older entry under an H1 heading with a `DD.MM.YYYY` date.',
       parsed: {
         _: [
-          'bark bark',
-          'woof',
-          'arf'
+          'An older entry under an H1 heading with a DD.MM.YYYY date.'
         ]
       }
     },
-    { version: '1.3.0',
-      title: 'v1.3.0',
+    { version: '1.0.0',
+      title: 'v1.0.0',
       date: null,
-      body: '* make it so',
+      body: '* First stable release.',
       parsed: {
         _: [
-          'make it so'
+          'First stable release.'
         ]
       }
     },
-    { version: '1.2.3',
-      title: '[1.2.3](link)',
+    { version: '0.9.0',
+      title: '[0.9.0](https://example.com/releases/0.9.0)',
       date: null,
-      body: '* init',
+      body: '* Initial public prototype.',
       parsed: {
         _: [
-          'init'
+          'Initial public prototype.'
         ]
       }
     }
@@ -253,6 +262,8 @@ Parsing the above example will return the following object:
 
 Expects versions to be [semver](http://semver.org/) compliant, otherwise sets `version` to null.
 
+Both `#` and `##` headings are treated as versions. The version number is read from the heading whether it is bare (`2.1.0`), `v`-prefixed (`v1.0.0`), or wrapped in brackets and optionally linked (`[0.9.0](...)`), and dates are recognized in common formats such as `YYYY-MM-DD`, `DD.MM.YYYY`, and parenthesized `(YYYY-MM-DD)`.
+
 Each entry is available as an object in the `versions` array. The body of a given entry can be accessed using the following properties:
 
 - `body` - A string containing all of the updates/changes/etc. for the current entry. This property includes both plain text and markdown.
