Releaser Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require woohoolabs/releaser
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Woohoolabs\Releaser\ReleaserServiceProvider::class,
   ],
   

2. Publish Config:

   php artisan vendor:publish --provider="Woohoolabs\Releaser\ReleaserServiceProvider" --tag="config"
   

   Edit config/releaser.php to match your project’s GitHub/GitLab repo, changelog paths, and versioning rules.

3. First Release:

   php artisan releaser:release --dry-run
   

   Verify the changelog and version bump before committing.

First Use Case: Bumping a Patch Version

1. Update Changelog:

   php artisan releaser:changelog "Fix typo in README"
   

   This appends the commit message to the Unreleased section of your changelog (e.g., CHANGELOG.md).

2. Release:

   php artisan releaser:release --patch
   

   • Auto-generates a Git tag (e.g., v1.0.1).
   • Commits the changelog updates.
   • Pushes tags to remote (if configured).

   New in 1.2.0: Disable tag signing with --no-signing:

   php artisan releaser:release --patch --no-signing
   

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks: Use releaser:changelog in a pre-commit hook to auto-categorize commits (e.g., feat:, fix:). Example Git hook:

   # .git/hooks/pre-commit
   #!/bin/bash
   if [[ "$(git diff --cached --name-only)" =~ CHANGELOG.md$ ]]; then
       exit 0
   else
       php artisan releaser:changelog "$(git log -1 --pretty=%B)"
   fi
   

2. CI/CD Pipeline: Trigger releases on merged PRs with semantic labels (e.g., major, minor):

   # .github/workflows/release.yml
   jobs:
     release:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: php artisan releaser:release --${{ github.event.pull_request.labels.* }} --no-signing
   

3. Custom Versioning: Override default semantic versioning by extending the Woohoolabs\Releaser\Versioner class:

   // app/Versioners/CustomVersioner.php
   namespace App\Versioners;
   use Woohoolabs\Releaser\Versioner;
   
   class CustomVersioner extends Versioner {
       protected function getVersion(): string {
           return 'v'.parent::getVersion().'-beta';
       }
   }
   

   Bind it in config/releaser.php:

   'versioner' => App\Versioners\CustomVersioner::class,
   

Common Patterns

• Changelog Templates: Customize the changelog template in config/releaser.php:

  'changelog' => [
      'template' => '## {{ .Version }} ({{ .Date }})',
      'sections' => [
          'Features' => 'feat:',
          'Bug Fixes' => 'fix:',
      ],
  ],
  

• Dry Runs: Always use --dry-run before actual releases to preview changes:

  php artisan releaser:release --dry-run --minor --no-signing
  

• Multi-Repository Projects: Use the --repo flag to manage releases for sub-packages:

  php artisan releaser:release --repo=packages/auth --patch --no-signing
  

Gotchas and Tips

Pitfalls

1. Changelog Conflicts:

   • Issue: Manual changelog edits may conflict with auto-generated entries.
   • Fix: Use git merge --no-ff to preserve changelog history or stash changes before releasing.

2. Tag Collisions:

   • Issue: Manual tags (e.g., v1.0.0) may conflict with auto-generated ones.
   • Fix: Configure config/releaser.php to prefix tags:

     'tag_prefix' => 'release/',
     

3. GitHub API Rate Limits:

   • Issue: Pushing tags may hit GitHub’s API limits if not authenticated.
   • Fix: Set up SSH keys or use a personal access token in .env:

     GITHUB_TOKEN=your_token_here
     

4. Tag Signing Overhead:

   • Issue: GPG signing may slow down CI/CD pipelines or fail due to missing keys.
   • Fix: Use --no-signing in CI/CD environments where signing isn’t required:

     php artisan releaser:release --patch --no-signing
     

Debugging

1. Verbose Output: Enable debug mode for detailed logs:

   php artisan releaser:release --debug --patch --no-signing
   

2. Commit Message Parsing:

   • If commits aren’t categorized correctly, check the regex in config/releaser.php under commit_types.
   • Example fix for custom prefixes:

     'commit_types' => [
         'feat'   => 'feature',
         'fix'    => 'bugfix',
         'docs'   => 'documentation',
         'refactor' => 'refactor',
     ],
     

3. Version File Issues:

   • Ensure composer.json has a valid version field (e.g., "version": "1.0.0").
   • If using custom version files, specify the path in config/releaser.php:

     'version_file' => 'version.txt',
     

4. Tag Signing Errors:

   • If GPG signing fails, verify your GPG key is configured in Git:

     git config --global user.signingkey YOUR_KEY_ID
     

   • Alternatively, disable signing with --no-signing:

     php artisan releaser:release --patch --no-signing
     

Extension Points

1. Custom Release Actions: Extend the Woohoolabs\Releaser\Release class to add post-release tasks (e.g., Slack notifications):

   // app/Releasers/CustomRelease.php
   namespace App\Releasers;
   use Woohoolabs\Releaser\Release;
   
   class CustomRelease extends Release {
       protected function afterRelease() {
           $this->notifySlack();
       }
   
       private function notifySlack() {
           // Logic to send Slack message
       }
   }
   

   Bind it in config/releaser.php:

   'release_class' => App\Releasers\CustomRelease::class,
   

2. Plugin System: Use Laravel’s service container to bind custom logic:

   // In a service provider
   $this->app->bind(
       Woohoolabs\Releaser\Contracts\ReleaseNotifier::class,
       App\Services\CustomNotifier::class
   );
   

3. Webhook Triggers: Create a Laravel route to trigger releases via HTTP:

   // routes/api.php
   Route::post('/release', function () {
       return \Artisan::call('releaser:release', [
           '--type' => request('type', 'patch'),
           '--dry-run' => true,
           '--no-signing' => true,
       ]);
   });
   

4. Conditional Signing: Dynamically enable/disable signing based on environment:

   // In a custom release class
   protected function shouldSignTag(): bool {
       return !app()->environment('production') || config('releaser.sign_tags');
   }