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 a CHANGELOG.md with the initial version 1.0.0 and all commits since the project's start.

3. Daily Workflow:

   • Commit messages must follow Conventional Commits (e.g., feat: add user auth, fix: login bug).
   • Run the command before releases to auto-generate changelog entries:

     composer changelog
     

Where to Look First

• Command Help: Run php vendor/bin/conventional-changelog --help for CLI options.
• Default Config: Inspect the config docs to override defaults.
• Example Output: Check the package’s CHANGELOG.md for formatting.

Implementation Patterns

Core Workflows

1. Pre-Release Changelog Generation:

   composer changelog --minor  # Auto-bumps to MINOR version (e.g., 1.0.0 → 1.1.0)
   

   • Use --major, --patch, or --rc to control versioning.
   • Laravel Integration: Add this to composer.json scripts:

     "scripts": {
       "release": "conventional-changelog --commit --annotate-tag",
       "release:patch": "conventional-changelog --patch --commit"
     }
     

2. Custom Config for Laravel Projects: Create .changelog in project root:

   return [
       'headerTitle' => 'Laravel Project Releases',
       'types' => ['feat', 'fix', 'docs', 'refactor'], // Override defaults
       'packageBump' => true, // Auto-update `composer.json` version
       'packageBumps' => [
           'ConventionalChangelog\PackageBump\ComposerJson',
           'ConventionalChangelog\PackageBump\PackageJson' // If using npm
       ],
       'prettyScope' => true, // Convert `auth:login` → `Auth: Login`
       'urlProtocol' => 'https',
       'issueUrlFormat' => 'https://github.com/{host}/{owner}/{repository}/issues/{number}'
   ];
   

3. CI/CD Integration:

   • GitHub Actions Example:

     - name: Generate Changelog
       run: composer changelog --minor --commit --annotate-tag
     

   • Trigger on git push to main with commit messages like release: v1.2.0.

4. Partial History: Generate changelog for a specific range (e.g., last 3 versions):

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

Laravel-Specific Tips

• Artisan Command Wrapper: 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
          {--type= : Release type (major|minor|patch)}
          {--commit : Auto-commit changes}';
  
      public function handle()
      {
          $process = new Process([
              'php', 'vendor/bin/conventional-changelog',
              '--' . ($this->option('type') ?: 'patch'),
              $this->option('commit') ? '--commit' : null
          ]);
          $process->run();
          $this->output->write($process->getOutput());
      }
  }
  

  Register in app/Console/Kernel.php:

  protected $commands = [
      \App\Console\Commands\GenerateChangelog::class,
  ];
  

  Now run with:

  php artisan changelog:generate --type=minor --commit
  

• Package Version Sync: Use packageBump: true in .changelog to auto-update composer.json version. For Laravel packages, ensure version in composer.json is updated before publishing.

Gotchas and Tips

Pitfalls

1. Commit Message Format:

   • Issue: Changelog ignores commits with malformed Conventional Commits (e.g., fix login bug → missing :).
   • Fix: Enforce commit hooks or use a tool like commitlint.
   • Laravel Hook: Add a commit-msg hook in .git/hooks/commit-msg:

     #!/bin/sh
     php artisan commit:validate $1 || exit 1
     

     (Use a package like laravel-commit-msg.)

2. Version Bump Conflicts:

   • Issue: Manual composer.json version edits conflict with auto-bumps.
   • Fix: Disable packageBump in .changelog and manually bump versions:

     'packageBump' => false,
     

     Or use --ver="1.2.0" to specify the version.

3. Git History Gaps:

   • Issue: --history overwrites CHANGELOG.md but may miss merged branches.
   • Fix: Use --merged to include only commits reachable from HEAD:

     composer changelog --history --merged
     

4. Annotated Tags:

   • Issue: --annotate-tag fails if git tag permissions are restricted.
   • Fix: Ensure the user has write access to the repo or use lightweight tags:

     composer changelog --no-tag
     

Debugging

• Dry Run: Test config changes without committing:

  composer changelog --no-commit --no-tag
  

• Verbose Output: Enable debug mode (not natively supported; use strace or wrap in a script to log process output).
• Config Validation: Validate .changelog syntax with:

  php -r 'include ".changelog"; var_dump($config);'
  

Extension Points

1. Custom Templates: Override the Markdown template by extending the package’s ChangelogGenerator:

   // app/Providers/AppServiceProvider.php
   use ConventionalChangelog\ChangelogGenerator;
   
   public function boot()
   {
       $generator = new ChangelogGenerator();
       $generator->setTemplate('custom-template.md'); // Path to your template
   }
   

2. Pre/Post Hooks: Use preRun and postRun in .changelog to integrate with Laravel events:

   'preRun' => function () {
       // Run before changelog generation (e.g., validate commits)
       \Log::info('Running pre-changelog hooks...');
   },
   'postRun' => function () {
       // Run after (e.g., notify Slack)
       \Artisan::call('notify:release');
   },
   

3. Custom Commit Parsing: Extend the CommitParser to handle Laravel-specific commit types (e.g., laravel: migrate):

   // app/Providers/AppServiceProvider.php
   use ConventionalChangelog\CommitParser;
   
   public function boot()
   {
       $parser = new CommitParser();
       $parser->addType('laravel', [
           'label' => 'Laravel Updates',
           'description' => 'Changes to Laravel-specific components'
       ]);
   }
   

Config Quirks

• Empty types vs. ignoreTypes:
  • types: [] → Only show commits with these types.
  • ignoreTypes: [] → Show all types (overrides defaults like chore).
• Path Resolution:
  • path in .changelog is relative to root. Use absolute paths if needed:

    'path' => '/full/path/to/CHANGELOG.md',
    

• Date Formats:
  • Customize dateFormat to match Laravel’s config('app.datetime_format'):

    'dateFormat' => 'Y-m-d H:i:s',
    

Performance

• Large Repos: Use --from-tag to limit history:

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