Laravel Ai Changelog Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require amjitk/laravel-ai-changelog
   php artisan vendor:publish --provider="AmjitK\LaravelAiChangelog\ServiceProvider" --tag="config"
   

   • Verify config/ai-changelog.php exists and adjust API keys (e.g., OpenAI) if needed.

2. First Use Case:

   • Generate a changelog entry for a recent commit:

     use AmjitK\LaravelAiChangelog\Facades\AiChangelog;
     
     $entry = AiChangelog::generate([
         'commit_message' => 'feat: add user authentication',
         'changes' => ['auth system', 'user model'],
     ]);
     

   • Output: AI-generated changelog markdown (e.g., ## Features\n- Added user authentication system...).

3. Key Files:

   • config/ai-changelog.php: API keys, default prompts.
   • app/Providers/AiChangelogServiceProvider.php: Override defaults if needed.

Implementation Patterns

Workflows

1. Automated Changelog Generation:

   • Hook into Git events (e.g., post-commit) via a custom Artisan command:

     // app/Console/Commands/GenerateChangelog.php
     public function handle() {
         $commits = $this->getRecentCommits(); // Custom logic
         foreach ($commits as $commit) {
             AiChangelog::generate(['commit_message' => $commit->message]);
         }
     }
     

   • Schedule daily via Laravel’s scheduler:

     $schedule->command('changelog:generate')->daily();
     

2. Integration with GitHub/GitLab:

   • Use webhooks to trigger changelog generation on PR merges:

     // routes/web.php
     Route::post('/webhooks/changelog', function (Request $request) {
         $payload = $request->json()->all();
         AiChangelog::generate([
             'commit_message' => $payload['pull_request']['title'],
             'changes' => $payload['commits'],
         ]);
     });
     

3. Custom Prompts:

   • Extend default prompts via config:

     'prompts' => [
         'feature' => 'Generate a concise changelog entry for this feature: {{commit_message}}',
         'bugfix' => 'Describe the fix for: {{commit_message}}',
     ],
     

   • Override dynamically:

     AiChangelog::generate(['commit_message' => 'fix: login bug'], ['prompt' => 'bugfix']);
     

4. Storage:

   • Save outputs to a file or database:

     $entry = AiChangelog::generate([...]);
     file_put_contents(storage_path('app/changelog.md'), $entry, FILE_APPEND);
     

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • Monitor OpenAI API calls (default: 3 requests/minute). Cache responses:

     $entry = AiChangelog::generate([...], ['cache' => true]); // Uses Laravel cache.
     

2. Commit Message Parsing:

   • AI may misinterpret vague commit messages (e.g., "update"). Use conventional commits (e.g., feat:, fix:).

3. Cost Management:

   • Long changelogs increase token usage. Limit input length:

     AiChangelog::generate([...], ['max_tokens' => 100]);
     

4. Dependency on External APIs:

   • Add retry logic for API failures:

     try {
         AiChangelog::generate([...]);
     } catch (\AmjitK\LaravelAiChangelog\Exceptions\ApiException $e) {
         // Retry or fallback to manual entry.
     }
     

Tips

1. Testing:

   • Mock AI responses in tests:

     AiChangelog::shouldReceive('callApi')->andReturn('## Test Entry');
     

2. Local Development:

   • Use null API keys in .env to bypass calls during testing.

3. Extending Functionality:

   • Add custom fields (e.g., breaking_changes):

     AiChangelog::extendPrompt(function ($prompt, $data) {
         return str_replace('{{changes}}', $data['breaking_changes'] ?? '', $prompt);
     });
     

4. Performance:

   • Batch commits for bulk generation:

     $entries = AiChangelog::batchGenerate([$commit1, $commit2]);
     

5. Fallback Mechanism:

   • Provide a manual override for failed AI calls:

     $entry = AiChangelog::generate([...], ['fallback' => 'Manual entry here.']);