README

PHP Conventional Changelog

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

Description

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 package can help to automatically generate changelog and release note files, so the developers of the project reduce the work that is necessary to finalize and check the new release of the project.

This package can generate a changelog from a project's committing history messages and metadata using composer and automate versioning with semver and conventional-commits.

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.

Look at our CHANGELOG file if you are looking for an example of a possible final result.

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.

📘 Requirements

php >= 7.1.3
git >= 2.1.4

📖 Installation

You can install it easily with composer

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

GitHub Action

The GitHub Action runs the changelog generator in a checked-out repository. Fetch the complete history so the generator can read all commits and tags:

name: Changelog

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: marcocesarato/php-conventional-changelog@v1
        with:
          arguments: |
            --no-change-without-commits

Pass one command argument per line. Keep an option value on the same line as its option, for example --ver=2.0.1 or --annotate-tag=Release 2.0.1. Use working-directory for a project in a subdirectory:

      - uses: marcocesarato/php-conventional-changelog@v1
        with:
          working-directory: packages/application
          arguments: |
            --history

The Action configures PHP for the whole job. It uses PHP 8.4 by default; set php-version to another version supported by the lockfile (currently PHP 8.4.1 or newer) when later steps need the same runtime.

To create and push a release commit and tag, grant write access, configure the Git author, and push the local changes created by the Action:

permissions:
  contents: write

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 0

  - name: Configure Git author
    run: |
      git config user.name "github-actions[bot]"
      git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

  - uses: marcocesarato/php-conventional-changelog@v1
    with:
      arguments: |
        --commit
        --no-change-without-commits

  - name: Push release
    run: git push --follow-tags

The Action executes the repository's .changelog PHP configuration and any configured hooks. Do not run a release job with write permissions or secrets against code from an untrusted pull request.

Publish to GitHub Marketplace

After this file and action.yml are on the public repository's default branch:

Open action.yml on GitHub and select Draft a release in the Marketplace banner.
Check Publish this Action to the GitHub Marketplace, choose a category, and accept the Marketplace Developer Agreement if GitHub asks.
Create a semantic version tag such as v1.18.0, then publish the release.
Create or update the moving v1 tag so workflows using @v1 receive compatible updates.

GitHub publishes the Marketplace listing from the root action.yml; no separate upload is required.

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:

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.

The examples below use Composer's executable proxy on Linux and macOS. On Windows, replace vendor/bin/conventional-changelog with vendor\bin\conventional-changelog.bat. You can also run the portable php vendor/bin/conventional-changelog form on every platform.

Notes:

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:

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

New version

To generate your changelog (without committing files)

vendor/bin/conventional-changelog

New release (with commit and tag)

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

vendor/bin/conventional-changelog --commit

or to amend at an existing commit you can run:

vendor/bin/conventional-changelog --amend

Annotated and Signed Tags

By default, the tool creates lightweight tags. You can create annotated or GPG-signed tags:

Create an annotated tag:

vendor/bin/conventional-changelog --commit --annotate-tag

Create a GPG-signed tag (requires GPG configuration):

vendor/bin/conventional-changelog --commit --sign-tag

Create an annotated tag with a custom message:

vendor/bin/conventional-changelog --commit --annotate-tag="Release version"

You can also configure this in your .changelog configuration file:

return [
    'annotateTag' => true,  // Create annotated tags by default
    'signTag' => true,      // Create GPG-signed tags by default
];

Note: GPG-signed tags (--sign-tag) are automatically annotated, so you don't need to use both options together.

History

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

Commits after the newest tag are included in the next release section. If the repository has no tags, the complete history through HEAD is included.

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

vendor/bin/conventional-changelog --history

Date range

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

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

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

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

Calendar versioning

Use --calver to generate versions in YYYY.MM.DD.PATCH format. PATCH starts at 0 and increments when another release is created on the same day:

vendor/bin/conventional-changelog --calver --commit

Pass a custom format using the YYYY, YY, MM, DD, and PATCH tokens:

vendor/bin/conventional-changelog --calver="YY.MM.PATCH" --commit

Commands List

Info: You can have more info by running vendor/bin/conventional-changelog --help

Description:
  Generate changelogs and release notes from a project's commit messagesand metadata and automate versioning with semver.org and conventionalcommits.org

Usage:
  changelog [options] [--] [<path>]

Arguments:
  path                               Specify the path directory where generate changelog

Options:
      --config=CONFIG                Specify the configuration file path
  -c, --commit                       Commit the new release once changelog is generated
  -a, --amend                        Amend commit the new release once changelog is generated
      --commit-all                   Commit all changes the new release once changelog is generated
      --first-release                Run at first release (if --ver isn't specified version code it will be 1.0.0)
      --from-date=FROM-DATE          Get commits from specified date [YYYY-MM-DD]
      --to-date=TO-DATE              Get commits last tag date (or specified on --from-date) to specified date [YYYY-MM-DD]
      --from-tag=FROM-TAG            Get commits from specified tag
      --to-tag=TO-TAG                Get commits last tag (or specified on --from-tag) to specified tag
      --major                        Major release (important changes)
      --minor                        Minor release (add functionality)
      --patch                        Patch release (bug fixes) [default]
      --rc                           Release candidate
      --beta                         Beta release
      --alpha                        Alpha release
      --ver=VER                      Specify the next release version code (semver)
      --calver[=CALVER]              Use calendar versioning [YYYY.MM.DD.PATCH] [default: false]
      --history                      Generate the entire history of changes of all releases
      --no-verify                    Bypasses the pre-commit and commit-msg hooks
      --no-tag                       Disable release auto tagging
      --no-change-without-commits    Do not apply change if no commits
      --annotate-tag[=ANNOTATE-TAG]  Make an unsigned, annotated tag object once changelog is generated [default: false]
      --sign-tag                     Make a GPG-signed tag object once changelog is generated
      --merged                       Only include commits whose tips are reachable from HEAD
  -h, --help                         Display help for the given command. When no command is given display help for the changelog command

marcocesarato / php-conventional-changelog

Package info

Security

Statistics