Getting Started

Minimal Setup

Installation:

composer require automattic/jetpack-changelogger

Add the service provider to config/app.php under providers:

Automattic\Jetpack\Changelogger\ChangeloggerServiceProvider::class,

Configuration: Publish the config file:
```
php artisan vendor:publish --provider="Automattic\Jetpack\Changelogger\ChangeloggerServiceProvider" --tag=config
```
Update config/changelogger.php to define:
- changelog_directory: Path to store changelog files (e.g., storage/changelogs).
- pr_prefix: Prefix for PR-based changelog files (e.g., pr-).
- default_template: Path to a template file for new changelog entries.
First Use Case: Drop a changelog file (e.g., storage/changelogs/pr-123.md) with content like:
```
## Feature
- Added new API endpoint for user profiles.

## Fixes
- Resolved issue with pagination in admin panel.
```
Run:
```
php artisan changelog:generate
```
This compiles all PR changelogs into a unified CHANGELOG.md in the root directory.

Implementation Patterns

Workflow Integration

Git Hooks: Automate changelog file creation via a pre-push or pre-commit hook:

echo '#!/bin/bash
php artisan changelog:create --pr=123 --message="Added feature X"' >> .git/hooks/pre-push
chmod +x .git/hooks/pre-push

CI/CD Pipeline: Trigger changelog generation on PR merge (e.g., GitHub Actions):
```
- name: Generate Changelog
  run: php artisan changelog:generate
```
Template Customization: Extend the default template by publishing assets:
```
php artisan vendor:publish --provider="Automattic\Jetpack\Changelogger\ChangeloggerServiceProvider" --tag=views
```
Modify resources/views/changelogger/template.blade.php to include custom sections (e.g., Breaking Changes).

Programmatic Usage: Create changelog entries dynamically in code:

use Automattic\Jetpack\Changelogger\Facades\Changelogger;

Changelogger::addEntry('pr-123', [
    'Feature' => ['Added OAuth2 support'],
    'Fixes' => ['Fixed CSRF token validation']
]);

Version Tagging: Use the changelog:tag command to associate changelogs with Git tags:
```
php artisan changelog:tag v1.2.0
```

Gotchas and Tips

Pitfalls

File Permissions: Ensure the changelog_directory is writable by the web server/user running Laravel:
```
chmod -R 775 storage/changelogs
```
PR Number Conflicts: Avoid duplicate PR numbers (e.g., rebased PRs). Use --force to overwrite:
```
php artisan changelog:create --pr=123 --force
```
Template Parsing Errors: Validate Blade syntax in custom templates. Test with:
```
php artisan changelog:generate --dry-run
```
Case Sensitivity: Changelog sections (e.g., ## Feature) must match the template’s expected keys. Use snake_case in code:
```
Changelogger::addEntry('pr-123', ['features' => ['New endpoint']]);
```

Debugging

Log Output: Enable debug mode in config/changelogger.php:
```
'debug' => env('CHANGELOGGER_DEBUG', false),
```
Check storage/logs/laravel.log for errors.
Dry Runs: Test changes without modifying files:
```
php artisan changelog:generate --dry-run
```

Extension Points

Custom Commands: Extend the base commands by binding new logic:

// app/Console/Commands/CustomChangelogCommand.php
use Automattic\Jetpack\Changelogger\Commands\ChangelogCommand;

class CustomChangelogCommand extends ChangelogCommand {
    protected $signature = 'changelog:custom {pr}';
    protected function handle() {
        // Custom logic
        $this->generateChangelog($this->argument('pr'));
    }
}

Event Listeners: Listen for changelog events (e.g., ChangelogGenerated):

// app/Providers/EventServiceProvider.php
protected $listen = [
    'Automattic\Jetpack\Changelogger\Events\ChangelogGenerated' => [
        'App\Listeners\NotifySlackOnChangelogUpdate',
    ],
];

API Integration: Fetch changelog data via a custom route:

Route::get('/api/changelog', function () {
    return Changelogger::getLatestEntries(5); // Returns last 5 entries
});

Jetpack Changelogger Laravel Package