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(9mo ago)14.6k1MITPHPPHP ^8.4CI passing

Since May 16Pushed 1mo ago2 watchersCompare

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

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

42

—

FairBetter than 88% of packages

Maintenance75

Regular maintenance activity

Popularity21

Limited adoption so far

Community11

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

290d 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 (48 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

[laravel/framework

The Laravel Framework.

34.8k543.8M20.1k](/packages/laravel-framework)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M507](/packages/pimcore-pimcore)[statamic/cms

The Statamic CMS Core Package

4.8k3.6M985](/packages/statamic-cms)[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)

9421.6k61](/packages/open-dxp-opendxp)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)

PHPackages © 2026

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