PHPackages                             decodelabs/chronicle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. decodelabs/chronicle

ActiveLibrary[Utility & Helpers](/categories/utility)

decodelabs/chronicle
====================

Release notes generator

v0.3.1(8mo ago)13.9k1MITPHPPHP ^8.4CI passing

Since May 16Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/decodelabs/chronicle)[ Packagist](https://packagist.org/packages/decodelabs/chronicle)[ RSS](/packages/decodelabs-chronicle/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (10)Dependencies (13)Versions (12)Used By (1)

Chronicle
=========

[](#chronicle)

[![PHP from Packagist](https://camo.githubusercontent.com/0db0d97e82f862f08dcf7d7cf17713a57b8f57855f8e368d8a398876e77a8343/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465636f64656c6162732f6368726f6e69636c653f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/chronicle)[![Latest Version](https://camo.githubusercontent.com/45778db5b6b3bb88a711956905622a33f1bdc9e500c13b5ca61530abfa7af766/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465636f64656c6162732f6368726f6e69636c652e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/chronicle)[![Total Downloads](https://camo.githubusercontent.com/c3d7278ca9660bb28ef1853414794c43aef8f49ce94e08bb20f20a82f21aac77/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465636f64656c6162732f6368726f6e69636c652e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/chronicle)[![GitHub Workflow Status](https://camo.githubusercontent.com/0b75f856377fc5217ac02fb5d7000571bf1feeb3595ba43636e32404c5a82b17/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f64656c6162732f6368726f6e69636c652f696e746567726174652e796d6c3f6272616e63683d646576656c6f70)](https://github.com/decodelabs/chronicle/actions/workflows/integrate.yml)[![PHPStan](https://camo.githubusercontent.com/e25c14ce011edabdd0fbd2e10415b41cc5d66ed11ef3e5b7edd074c5bdd35a2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d656e61626c65642d3434434331312e7376673f6c6f6e6743616368653d74727565267374796c653d666c6174)](https://github.com/phpstan/phpstan)[![License](https://camo.githubusercontent.com/28362583ec4fc8f52f8c8bbffdd9012572f5bbf4725ca07164069c91d2bc8fc9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6465636f64656c6162732f6368726f6e69636c653f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/chronicle)

### Release notes generator

[](#release-notes-generator)

Chronicle provides a set of tools for parsing, generating and rendering release notes and change logs.

---

Installation
------------

[](#installation)

This package requires PHP 8.4 or higher.

Install via Composer:

```
composer require decodelabs/chronicle
```

Usage
-----

[](#usage)

Open a `Repository` in the root of your project and pass in a `Systemic` service instance.

```
use DecodeLabs\Chronicle\Repository;
use DecodeLabs\Monarch;
use DecodeLabs\Systemic;

$repo = new Repository(
    '/path/to/your/repo',
    Monarch::getService(Systemic::class)
);
```

Parse your existing change log file - name defaults to `CHANGELOG.md`. Set rewrite to `true` to reformat release headers and layout in Chronicle's format - useful for converting existing change logs.

If your change log file doesn't exist, an empty template document will be created.

```
$doc = $repo->parseChangeLog(
    fileName: 'CHANGELOG.md',
    rewrite: true
);
```

### Structure

[](#structure)

The parser expects three main sections in the change log file:

- **Preamble**: This is the first section of the file, which contains general information about the change log
- **Unreleased**: This section contains unreleased changes, which are not yet assigned to a specific version
- **Releases**: This section contains the list of released versions, each with its own set of changes

```
# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

- This is a block of unreleased changes
- It is used to generate the next release

It doesn't have a version number, and can be in list or free text format. It just requires an "Unreleased" header.

## [v0.2.0](https://github.com/decodelabs/chronicle/commits/v0.2.0) - 16th May 2025

- Added a new feature

[Full list of changes](https://github.com/decodelabs/chronicle/compare/v0.1.0...v0.2.0)

## [v0.1.0](https://github.com/decodelabs/chronicle/commits/v0.1.0) - 15th May 2025

- Implemented basic ChangeLog parser
- Implemented ChangeLog document renderer
- Built GitHub issue and pull request fetchers
```

### Next release

[](#next-release)

You can add unreleased changes to the change log in the `Unreleased` section as you work on your project. When you're ready to release a new version, you can use the `generateNextRelease()` method to turn those changes into a new release.

```
$doc->generateNextRelease(
    version: 'patch', // major, minor, patch, preRelease, breaking, feature or v0.2.0
    date: '2025-05-16', // optional, defaults to today
    repository: $repo
);
```

if your project is hosted on GitHub, `generateNextRelease()` will automatically fetch the latest issues and pull requests from the repository and add them to the release notes.

if your project is private or you hit the API rate limit, you can place your access token in your `.env` file with the key `GITHUB_TOKEN`. Chronicle will automatically authenticate with the GitHub API using this token.

```
## [v0.2.0](https://github.com/decodelabs/chronicle/commits/v0.2.0) - 16th May 2025

- Added a new feature

### Merged Pull Requests
- [#123](https://github.com/decodelabs/chronicle/pull/123) - Fixed an issue
- [#456](https://github.com/decodelabs/chronicle/pull/456) - Added another new feature

### Issues
- [#789](https://github.com/decodelabs/chronicle/issues/789) - Fixed a bug
```

### Rendering

[](#rendering)

You can render the change log document to a string using the `render()` method, or back to the original file using `save()`. When you call either of these methods, you can specify a `Renderer` implementation which you can use to customize the output format. If ommitted, the default renderer will be used.

```
use DecodeLabs\Chronicle\ChangeLog\Renderer;
use MyApp\Chronicle\ChangeLog\Renderer\MyCustomRenderer;

$doc->render(
    renderer: new MyCustomRenderer() // Instance of Renderer
);
```

Licensing
---------

[](#licensing)

Chronicle is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance66

Regular maintenance activity

Popularity21

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~13 days

Recently: every ~25 days

Total

10

Last Release

244d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a241d64d12b3b5ee94197862ec1ec30b82ed2efa34a0cd7f4c3565a021daddd?d=identicon)[betterthanclay](/maintainers/betterthanclay)

---

Top Contributors

[![betterthanclay](https://avatars.githubusercontent.com/u/1273586?v=4)](https://github.com/betterthanclay "betterthanclay (43 commits)")

### Embed Badge

![Health badge](/badges/decodelabs-chronicle/health.svg)

```
[![Health](https://phpackages.com/badges/decodelabs-chronicle/health.svg)](https://phpackages.com/packages/decodelabs-chronicle)
```

###  Alternatives

[ashallendesign/favicon-fetcher

A Laravel package for fetching website's favicons.

190272.4k3](/packages/ashallendesign-favicon-fetcher)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[aeliot/todo-registrar

Register TODOs from source code in issue tracker

153.0k](/packages/aeliot-todo-registrar)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

7310.3k29](/packages/open-dxp-opendxp)[ralphjsmit/laravel-helpers

A package containing handy helpers for your Laravel-application.

13704.6k2](/packages/ralphjsmit-laravel-helpers)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)