PHP Conventional Changelog: Generate changelog and release notes from commit

Recommend this page to a friend!
  Info   View files Documentation   View files View files (14)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog (1)    
Last Updated Ratings Unique User Downloads Download Rankings
2021-01-18 (1 month ago) RSS 2.0 feedNot yet rated by the usersTotal: 22 This week: 1All time: 10,174 This week: 332Up
Version License PHP version Categories
php-conventional-cha 1.4.0Free for non-comm...5PHP 5, Utilities and Tools, Console, P...
Description Author

This class can generate changelog and release notes from commit.

It provides a command that can be run from the command line to generate changelog files and release notes files for the current project using PHP composer.

The command may take parameters that defines the versions of the projects that will be considered to extract the changes in the project to generate the files.

The package uses a configuration script with the option values that will be used to customize the way you may want to have changelog and release notes be generated.

Innovation Award
PHP Programming Innovation award nominee
January 2021
Number 3
When a new release of a software project is announced, it is convenient to generate documents that let the project users know what were the changes and other relevant notes about the new project release.

This class can help to automatically generate change log and release note files, so the developers of the project reduce the work that is necessary to finalize the new release of the project.

Manuel Lemos
Picture of Marco Cesarato
  Performance   Level  
Name: Marco Cesarato <contact>
Classes: 9 packages by
Country: Italy Italy
Innovation award
Innovation award
Nominee: 2x

Details

<div align="center">

<h1 align="center">PHP Conventional Changelog</h1>

Version Requirements Conventional Commits License GitHub

If this project helped you out, please support us with a star :star:

<br>

![](docs/images/logo.png)

</div>

Description

Generate changelogs from a project's commit messages and metadata using composer and automate versioning with semver and conventional-commits.

This package can generate changelog and release notes from committing history. It provides a command that can be run from the terminal, or using composer scripts, to generate a changelog file in markdown for the current project.

The command may take parameters that define the releases of the project that will be considered to extract the changes from the git history to generate the file. The package uses a configuration system with that permit to customize the settings you may want to have your desired changelog generated.

How to contribute

Have an idea? Found a bug? Please raise to ISSUES or PULL REQUEST. Contributions are welcome and are greatly appreciated! Every little bit helps.

? Installation

You can install it easily with composer

composer require --dev marcocesarato/php-conventional-changelog

Scripts (Optional)

For easy use the changelog generator or release faster your new version you can add to your composer.json the scripts:

> Notes: you can customize it according to your needs

{
  ...
  "scripts": {
    "changelog": "conventional-changelog",
    "release": "conventional-changelog --commit",
    "release:patch": "conventional-changelog --patch --commit",
    "release:minor": "conventional-changelog --minor --commit",
    "release:major": "conventional-changelog --major --commit"
  },
  ...
}

Now you can just run composer changelog or composer release (the last one will autobump the version code and commit changes) to generate your changelog.

? Configuration

> Notes: this procedure is optional and permit to overwriting/merging the default settings

For customize settings you just needs to create a file named .changelog on the root of your project/on the working dir or use the --config option to specify the location of your configuration file.

> Notes:<br> > - When a setting on the configuration file is not necessary just omit it > - The default ignored types are: build, chore, ci, docs, perf, refactor, revert, style, test > - To allow all types just keep empty types and set empty ignoreTypes

You can have more info about reading the config documentation.

? Usage

The changelog generator will generate a log of changes from the date of the last tag to the current date, and it will put all commit logs in the latest version just created.

![](docs/images/usage.gif)

> Notes:<br> > - Some of these options listed on examples could be used together at the same time (ex. --first-release --commit) > - Auto bump of version code using the Semantic Versioning (MAJOR.MINOR.PATCH) is enabled by default if not specified the release method. > - MAJOR: At least one breaking change. > - MINOR: At least one new feature. > - PATCH: Default > - Use these options to specify the release method: --major, --minor, --patch, --rc, --beta, --alpha.

Examples

First version

> Notes: use this option only if you don't need all history changes or is the first version, else run with --history option

To generate your changelog for the first version run:

php vendor/bin/conventional-changelog --first-release

New version

To generate your changelog (without committing files)

php vendor/bin/conventional-changelog

New release (with commit and tag)

To generate your changelog with auto commit and auto versioning tagging run:

php vendor/bin/conventional-changelog --commit

or to amend at an existing commit you can run:

php vendor/bin/conventional-changelog --amend

History

To generate your changelog with the entire history of changes of all releases

> Warn: this operation will overwrite the CHANGELOG.md file if it already exists

php vendor/bin/conventional-changelog --history

Date range

To generate your changelog from a specified date to another specified date

php vendor/bin/conventional-changelog --from-date="2020-12-01" --to-date="2021-01-01"

Tag range

To generate your changelog from a specified tag to another specified tag

php vendor/bin/conventional-changelog --from-tag="v1.0.2" --to-tag="1.0.4"

Specific version

To generate your changelog with a specific version code

php vendor/bin/conventional-changelog --ver="2.0.1"

Commands List

> Info: You can have more info about running php vendor/bin/conventional-changelog --help

        --config          str         Specify the configuration file path
-c      --commit          bool        Commit the new release once changelog is generated
        --commit-all      bool        Commit all changes the new release once changelog is generated
-a      --amend           bool        Amend commit the new release once changelog is generated
        --major           bool        Major release (important changes)
        --minor           bool        Minor release (add functionality)
        --patch           bool        Patch release (bug fixes) [default]
        --rc              bool        Release Candidate
        --beta            bool        Beta release
        --alpha           bool        Alpha release
        --first-release   bool        Run at first release (if --ver isn't specified version code will be 1.0.0)
        --to-date         str         Get commits from last tag date (or specified on --from-date) to specified date [YYYY-MM-DD]
        --from-date       str         Get commits from specified date [YYYY-MM-DD]
        --to-tag          str         Get commits from last tag (or specified on --from-tag) to specified tag
        --from-tag        str         Get commits from specified tag
        --ver             str         Specify the next release version code (semver)
        --history         bool        Generate the entire history of changes of all releases
        --no-verify       bool        Skip the pre-commit and commit-msg hooks
        --no-tag          bool        Disable release auto tagging when commit enabled
  Files folder image Files  
File Role Description
Files folder imagesrc (5 files)
Accessible without login Plain text file .changelog Data Auxiliary data
Accessible without login Plain text file .changelog Data Auxiliary data
Accessible without login Plain text file .php_cs Example Example script
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file conventional-changelog Example Example script
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file README.md Doc. Documentation
Accessible without login Plain text file TODO.md Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
  Plain text file Changelog.php Class Class source
  Plain text file Configuration.php Class Class source
  Plain text file DefaultCommand.php Class Class source
  Plain text file Git.php Class Class source
  Plain text file Utils.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:22
This week:1
All time:10,174
This week:332Up

For more information send a message to info at phpclasses dot org.