Php Conventional Changelog Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

2. First Run (for a new project):

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

   This generates CHANGELOG.md with all commits since the project's inception.

3. Daily Workflow:

   composer changelog
   

   (Assuming you’ve added the script to composer.json as shown in the README.)

Where to Look First

• Command Help: Run php vendor/bin/conventional-changelog --help to explore all options.
• Default Config: Review the default settings in docs/config.md to understand customization points.
• Example Changelog: Check the project’s CHANGELOG.md for output formatting.

First Use Case

Automate Release Notes:

1. Commit changes with Conventional Commits (e.g., feat: add user authentication).
2. Run:

   composer release:patch  # Auto-bumps patch version, generates changelog, and commits/tags.
   

3. Push the changes:

   git push --follow-tags
   

Implementation Patterns

Core Workflows

1. Standard Release Cycle

• Pre-release:

  composer changelog --minor  # Dry-run to preview changes.
  

• Release:

  composer release:minor     # Auto-bumps version, generates changelog, commits, and tags.
  

• Post-release:

  git push origin main --follow-tags
  

2. Customized Changelog Generation

• Filter Commits by Type:

  composer changelog --ignore-types="docs,style"
  

• Date Range:

  composer changelog --from-date="2023-01-01" --to-date="2023-06-30"
  

• Tag Range:

  composer changelog --from-tag="v1.0.0" --to-tag="v2.0.0"
  

3. Integration with CI/CD

• GitHub Actions Example:

  - name: Generate Changelog
    run: composer changelog --no-verify
  - name: Create Release
    uses: softprops/action-gh-release@v1
    if: contains(github.ref, 'tags/')
    with:
      generate_release_notes: false  # Disable auto-notes (we use our changelog)
  

4. Configuration-Driven Workflows

• Project-Specific .changelog File:

  return [
      'headerTitle' => 'My Awesome Project - Release Notes',
      'types' => ['feat', 'fix', 'docs'],  // Only show these types
      'ignorePatterns' => ['/WIP:/'],     // Skip WIP commits
      'packageBump' => true,               // Auto-update composer.json version
      'annotateTag' => true,               // Use annotated tags
  ];
  

• Run with Custom Config:

  composer changelog --config=.changelog.custom
  

5. Post-Processing

• Pre/Post Hooks:

  return [
      'preRun' => function () {
          // Run tests before generating changelog
          shell_exec('php artisan test');
      },
      'postRun' => function () {
          // Notify Slack after release
          file_put_contents('release_notice.txt', 'New version released!');
      },
  ];
  

Laravel-Specific Patterns

1. Artisan Command Integration

Create a custom Artisan command to wrap the changelog generator:

// app/Console/Commands/GenerateChangelog.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;

class GenerateChangelog extends Command
{
    protected $signature = 'changelog:generate
        {--minor|major|patch=patch : Release type}
        {--commit : Auto-commit changes}
        {--no-verify : Bypass hooks}';

    public function handle()
    {
        $process = new Process([
            'php', 'vendor/bin/conventional-changelog',
            $this->option('minor') ? '--minor' : '',
            $this->option('patch') ? '--patch' : '',
            $this->option('commit') ? '--commit' : '',
            $this->option('no-verify') ? '--no-verify' : '',
        ]);
        $process->run();
        $this->output->write($process->getOutput());
    }
}

Usage:

php artisan changelog:generate --minor --commit

2. Versioning with Laravel Mix/Package Development

• Auto-Bump composer.json: Ensure packageBump: true in .changelog to update the version in composer.json during releases.
• Publish Assets: Add a post-run hook to publish assets (e.g., for frontend packages):

  'postRun' => function () {
      shell_exec('npm run prod && php artisan vendor:publish --tag=public');
  },
  

3. Release Notes in Laravel Admin Panels

• Embed Changelog in Backend: Fetch the latest changelog entry in a controller:

  public function showReleaseNotes()
  {
      $changelog = file_get_contents(base_path('CHANGELOG.md'));
      $latestVersion = preg_match('/## \[\d+\.\d+\.\d+\]/', $changelog, $matches)
          ? $matches[0] : 'Unreleased';
      return view('admin.release-notes', compact('changelog', 'latestVersion'));
  }
  

4. Git Hooks for Enforcement

• Commit Message Validation: Add a commit-msg hook to enforce Conventional Commits:

  # .git/hooks/commit-msg
  #!/bin/sh
  php vendor/bin/conventional-changelog --no-verify --dry-run | grep -q "is not a Conventional Commit"
  if [ $? -eq 0 ]; then
      echo "❌ Commit message must follow Conventional Commits."
      exit 1
  fi
  

Gotchas and Tips

Pitfalls

1. Git History Corruption:

   • Issue: Running --history on a project with a corrupted or non-linear git history (e.g., rebased commits) may produce incorrect changelogs.
   • Fix: Use --merged to only include commits reachable from HEAD:

     composer changelog --history --merged
     

2. Version Bump Conflicts:

   • Issue: If composer.json is manually edited, packageBump may overwrite changes or cause merge conflicts.
   • Fix: Review composer.json after running the command or use --no-tag to skip version bumping.

3. Case-Sensitive Tag Prefixes:

   • Issue: Tag prefixes (e.g., v) are case-sensitive. v1.0.0 ≠ V1.0.0.
   • Fix: Standardize prefixes in .changelog:

     'tagPrefix' => 'v',
     

4. GPG-Signed Tags Failures:

   • Issue: --sign-tag may fail if GPG is not configured or the key is not available.
   • Fix: Test GPG setup first:

     gpg --list-secret-keys --keyid-format LONG
     

   • Ensure the key is exported and available in the CI environment.

5. Composer Lock File Conflicts:

   • Issue: packageLockCommit: true may cause conflicts if composer.lock is edited manually.
   • Fix: Stash changes or use --no-tag to skip committing locks.

6. Date Range Quirks:

   • Issue: --from-date/--to-date may include commits outside the intended range if the repo has a non-standard commit date format.
   • Fix: Use --from-tag/--to-tag for more reliable ranges.

7. Conventional Commits Parsing Errors:

   • Issue: Non-standard commit messages (e.g., missing ! for breaking changes) may not parse correctly.
   • Fix: Validate commit messages with:

     composer changelog --dry-run
     

Debugging Tips

1. Dry Runs: Always test with