PHPackages automattic/jetpack-changelogger - 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. [CLI & Console](/categories/cli) 4. / 5. automattic/jetpack-changelogger ActiveProject[CLI & Console](/categories/cli) automattic/jetpack-changelogger =============================== Jetpack Changelogger tool. Allows for managing changelogs by dropping change files into a changelog directory with each PR. v6.0.14(3mo ago)106.7M—2.3%420GPL-2.0-or-laterPHPPHP >=7.2.5CI failing Since Mar 8Pushed 1mo ago3 watchersCompare [ Source](https://github.com/Automattic/jetpack-changelogger)[ Packagist](https://packagist.org/packages/automattic/jetpack-changelogger)[ RSS](/packages/automattic-jetpack-changelogger/feed)WikiDiscussions trunk Synced 1mo ago READMEChangelogDependencies (5)Versions (78)Used By (20) Jetpack Changelogger ==================== [](#jetpack-changelogger) This tool allows for managing a changelog for your project by having each PR drop a specially-formatted "change file" into a `changelog` directory, which the tool can then process when you make a release. Why? ---- [](#why) Traditional changelog files have one major disadvantage in a project with many things going on at once: merge conflicts! Multiple PRs are likely to be inserting changelog entries at the same place in the file, so when one is merged the other needs to be rebased. And, unfortunately, GitHub and other hosts seldom offer support for custom merge engines that might mitigate this. The use of "change files" in a directory works around this, since file creation won't conflict unless two people happen to choose the same filename for their PRs. This tool defaults to basing the filename on the git branch name, which again people usually choose to be unique enough. The use of change files also allows us to include additional metadata about the change, in particular the semantic versioning "significance". This means the release manager no longer has to determine on their own whether the new version should have a patch, minor, or major bump as the change files themselves already specify the kind of bump that's needed. Installation ------------ [](#installation) Require using `composer require --dev automattic/jetpack-changelogger`. This will install the `changelogger` tool into `vendor/bin/`, which you might add to your PATH, or you might run it via `composer exec -- changelogger`. If you're using `git`, it's recommended to also create `changelog/.gitkeep` in your repository so the directory will always be present. Configuration ------------- [](#configuration) Changelogger is configured via entries in composer.json, under `extra.changelogger`. In most cases you can set the configuration using `composer config extra.changelogger.$setting $value`. - **changelog**: Specifies the changelog file, relative to the composer.json. Default is `CHANGELOG.md`. - **changes-dir**: Specifies the directory holding changes files, relative to the composer.json. Default is `changelog`. - **link-template**: Template for creating changelog entry links. `${new}` is replaced with the URL-encoded new version number, `${old}` with the old. - **ordering**: Specifies the ordering of change entries: by type ('subheading'), 'significance', 'timestamp', and/or 'content'. Default is `[ 'subheading', 'content' ]`. - **types**: Specifies the types of changes used in the repository; see [Type field](#type-field). The value is a JSON object, with keys being the field value in the change file and values being the subheading text used in the combined changelog file. May be empty; the default is to use the types listed at . - **formater**: Plugin for parsing and formatting the changelog. Default is `keepachangelog`. - **versioning**: Versioning plugin used to determine new versions. Default is `semver`. Usage ----- [](#usage) ### Adding a change file [](#adding-a-change-file) The changelog file consists of named fields, a blank line, and the changelog entry content. ``` Significance: major Type: added Comment: This is an example. Initial commit! ``` The filename in the `changelog` directory does not matter, as long as it does not begin with a dot. A changelog file may be created interactively using `changelogger add`. You may also specify all the needed fields non-interactively with command line options; see `changelogger add --help` for details. #### Significance field [](#significance-field) This field specifies the significance of the change in the style of [semantic versioning](https://semver.org/). Valid values are - **patch**: Backwards-compatible bug fixes. - **minor**: Added (or deprecated) functionality in a backwards-compatible manner. - **major**: Broke backwards compatibility in some way. Depending on the `versioning` [configuration setting](#configuration), this may be used to determine the version when rolling the change files into a new changelog version. #### Type field [](#type-field) This specifies the type of the change, which in turn is used to place the entry in a proper subheading when rolling the change files into a new changelog version. Valid types are defined in the `types` [configuration setting](#configuration). If that setting is empty, the Type field should be omitted. #### Comment field [](#comment-field) This field contains arbitrary text that might be useful in communicating to other developers. It is not used by Changelogger. #### Changelog entry [](#changelog-entry) The changelog entry comes after all the fields, separated from them by a blank line. This is the text that is included in the changelog file when the change files are combined into a changelog version. When the [significance](#significance-field) is "patch", the entry may be left empty. It is not valid to leave it empty when the significance is "minor" or "major". ### Validating change files [](#validating-change-files) Change files may be validated using `changelogger validate`. By default it will check all non-dotfiles in the [configured](#configuration) `changes-dir`, but a list of specific files may be passed instead. When errors or warnings are encountered, by default the full path to the file is reported. This may be overridden using `--basedir`, which will cause paths inside that directory to be reported relative to it. ### Checking versions [](#checking-versions) To allow easier integration of changelogger into other tooling, the current, previous, and next versions based on the current may be printed with `changelogger version`. When fetching the next version, the same flags accepted by `changelogger write` to control the versioning are accepted here too. ### Updating the changelog [](#updating-the-changelog) The change files may be combined into a new changelog entry using `changelogger write`. Note that this operation will delete the change files, so you're encouraged to have checked them into git beforehand in case something goes wrong. Command line options allow for specifying prerelease suffixes (like `-dev` or `-beta`), overriding the version determination entirely, or amending the latest changelog entry. Plugins ------- [](#plugins) Plugins are used to parse the changelog file and to determine the next version from a current version. A plugin is specified by a JSON string, or an object with one of the following keys: - **name**: See below, or plugin documentation. - **class**: Plugin class name. Must be available via the autoloader. - **filename**: File from which to load the plugin class. The file must define exactly one class of the appropriate interface. The plugin may take additional keys as configuration. See the plugin documentation for details. If a string is given, it is assumed to be the `name`. ### Included plugins [](#included-plugins) One formatting plugin and two versioning plugins are included. #### "keepachangelog" formatting plugin [](#keepachangelog-formatting-plugin) This formatter parses a changelog in markdown format as documented at . Configuration options are: - **bullet**: String to use to bullet changelog entries. Default is `-`. - **dateFormat**: [PHP date formatting string](https://www.php.net/manual/en/datetime.format.php) used to output timestamps for each version. Default is `Y-m-d`. #### "semver" versioning plugin [](#semver-versioning-plugin) Determines the next version using the [significance](#significance-field) of the changes, per [semantic versioning](https://semver.org/). #### "wordpress" versioning plugin [](#wordpress-versioning-plugin) WordPress, and some of its plugins such as Jetpack, give normal releases decimal version numbers such as 9.4, incrementing it by 0.1 with each release. There is no special significance to going from 8.9 to 9.0. Bugfix "point releases" add a suffix like 9.4.1. When this plugin is in use, the [version](#checking-versions) and [write](#updating-the-changelog)commands will accept a `--point-release` option to indicate that a point release increment should be done rather than a major release. ### Writing plugins [](#writing-plugins) A formatting plugin must implement the `Automattic\Jetpack\Changelogger\FormatterPlugin` interface. A versioning plugin must implement the `Automattic\Jetpack\Changelogger\VersioningPlugin` interface. If you want your plugin to be available via a `name`, create an alias to it from `Automattic\Jetpack\Changelogger\Plugins\{Name}Formatter` or `Automattic\Jetpack\Changelogger\Plugins\{Name}Versioning`as appropriate for its type, and make sure that alias can be loaded via the autoloader. There are two common ways to do this correctly: 1. Using PSR-0 or PSR-4, put the `class_alias()` in the same file as the *target* class, and create a dummy file at the aliased name with a `class_exists()` call for the target name to trigger loading. 2. Use `.autoload.files` in composer.json to load a file with the necessary `class_alias()` calls. Note this will load all aliases classes on every request. ### Health Score 62 — FairBetter than 99% of packages Maintenance86 Actively maintained with recent releases Popularity51 Moderate usage in the ecosystem Community44 Growing community involvement Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 51.3% 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 ~25 days Recently: every ~18 days Total 73 Last Release 95d ago Major Versions v1.2.1 → v2.0.02021-09-28 v2.0.1 → v3.0.02021-10-13 v3.3.11 → v4.0.02023-11-20 v4.2.8 → v5.0.02024-11-14 v5.1.0 → v6.0.02025-02-24 PHP version history (4 changes)v1.0.0PHP >=5.6 v4.0.0PHP >=7.0 v5.0.0PHP >=7.2 v5.1.0PHP >=7.2.5 ### Community Maintainers ![](https://www.gravatar.com/avatar/7c5869ecbb8e0eac7e8b8e0f3cf7bdd8d5fcdc4abc10a72281872c53f8639d44?d=identicon)[automattic](/maintainers/automattic) ![](https://www.gravatar.com/avatar/11609890f6e7a840715f4cfc9622d77ea64b7dfc024df5643fbf8471a18c00f3?d=identicon)[kraft](/maintainers/kraft) ![](https://www.gravatar.com/avatar/5326730499ec14e274f51b9bcc39db6aac0fb38b33849715aae0e2587a2b93df?d=identicon)[jeherve](/maintainers/jeherve) ![](https://www.gravatar.com/avatar/6e220e167e341c28b1aa10bf0bb0374999068329f8683d3187ee3cf6749b8837?d=identicon)[dereksmart](/maintainers/dereksmart) --- Top Contributors [![anomiex](https://avatars.githubusercontent.com/u/1030580?v=4)](https://github.com/anomiex "anomiex (102 commits)")[![tbradsha](https://avatars.githubusercontent.com/u/32492176?v=4)](https://github.com/tbradsha "tbradsha (17 commits)")[![jeherve](https://avatars.githubusercontent.com/u/426388?v=4)](https://github.com/jeherve "jeherve (17 commits)")[![samiff](https://avatars.githubusercontent.com/u/15803018?v=4)](https://github.com/samiff "samiff (11 commits)")[![kraftbj](https://avatars.githubusercontent.com/u/88897?v=4)](https://github.com/kraftbj "kraftbj (10 commits)")[![zinigor](https://avatars.githubusercontent.com/u/374293?v=4)](https://github.com/zinigor "zinigor (8 commits)")[![coder-karen](https://avatars.githubusercontent.com/u/16754605?v=4)](https://github.com/coder-karen "coder-karen (5 commits)")[![sdixon194](https://avatars.githubusercontent.com/u/33553323?v=4)](https://github.com/sdixon194 "sdixon194 (3 commits)")[![gmjuhasz](https://avatars.githubusercontent.com/u/36671565?v=4)](https://github.com/gmjuhasz "gmjuhasz (3 commits)")[![manzoorwanijk](https://avatars.githubusercontent.com/u/18226415?v=4)](https://github.com/manzoorwanijk "manzoorwanijk (2 commits)")[![ice9js](https://avatars.githubusercontent.com/u/8056203?v=4)](https://github.com/ice9js "ice9js (2 commits)")[![mdbitz](https://avatars.githubusercontent.com/u/5784663?v=4)](https://github.com/mdbitz "mdbitz (1 commits)")[![miguelxpn](https://avatars.githubusercontent.com/u/12788275?v=4)](https://github.com/miguelxpn "miguelxpn (1 commits)")[![nunyvega](https://avatars.githubusercontent.com/u/16329583?v=4)](https://github.com/nunyvega "nunyvega (1 commits)")[![pablinos](https://avatars.githubusercontent.com/u/96462?v=4)](https://github.com/pablinos "pablinos (1 commits)")[![paulopmt1](https://avatars.githubusercontent.com/u/1044309?v=4)](https://github.com/paulopmt1 "paulopmt1 (1 commits)")[![psealock](https://avatars.githubusercontent.com/u/1922453?v=4)](https://github.com/psealock "psealock (1 commits)")[![sergeymitr](https://avatars.githubusercontent.com/u/1341249?v=4)](https://github.com/sergeymitr "sergeymitr (1 commits)")[![simison](https://avatars.githubusercontent.com/u/87168?v=4)](https://github.com/simison "simison (1 commits)")[![jwebbdev](https://avatars.githubusercontent.com/u/1992658?v=4)](https://github.com/jwebbdev "jwebbdev (1 commits)") --- Tags clidevchangelogkeepachangelog ### Embed Badge ![Health badge](/badges/automattic-jetpack-changelogger/health.svg) ``` [![Health](https://phpackages.com/badges/automattic-jetpack-changelogger/health.svg)](https://phpackages.com/packages/automattic-jetpack-changelogger) ``` ### Alternatives [nunomaduro/collision Cli error handling for console/command-line PHP applications. 4.6k331.8M8.5k](/packages/nunomaduro-collision)[symfony/maker-bundle Symfony Maker helps you create empty commands, controllers, form classes, tests and more so you can forget about writing boilerplate code. 3.4k111.1M568](/packages/symfony-maker-bundle)[crunzphp/crunz Schedule your tasks right from the code. 2292.0M6](/packages/crunzphp-crunz)[helhum/typo3-console A reliable and powerful command line interface for TYPO3 CMS 2939.0M192](/packages/helhum-typo3-console)[buggregator/trap A simple and powerful tool for debugging PHP applications. 2591.7M40](/packages/buggregator-trap)[laminas/laminas-cli Command-line interface for Laminas projects 563.7M54](/packages/laminas-laminas-cli) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)