Git Changelog Generator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alessandro_podo/git-changelog-generator
   

   Add the bundle to config/bundles.php:

   return [
       AlessandroPodo\GitChangelogGenerator\GitChangelogGenerator::class => ['all' => true],
   ];
   

2. Basic Configuration: Create config/packages/git_changelog_generator.yaml with minimal scopes:

   git_changelog_generator:
     scopes:
       - feature
       - bugfix
       - refactor
   

3. First Use Case: Generate a changelog for the last 10 commits:

   use AlessandroPodo\GitChangelogGenerator\Service\Changelog\Changelog;
   
   public function changelog(Changelog $changelog): Response
   {
       $content = $changelog->render(['limit' => 10]);
       return $this->render('changelog.html.twig', ['content' => $content]);
   }
   

4. Twig Template:

   {% extends 'base.html.twig' %}
   {% block body %}
       {{ content|raw }}
   {% endblock %}
   

Implementation Patterns

Workflow Integration

1. Commit Message Conventions: Use structured commit messages with footers for metadata:

   feat: Add user authentication
   footer: title: User Auth | description: JWT-based auth | visibility: public
   

   Or use scopes directly:

   feature: Add user auth
   

2. Dynamic Changelog Routes:

   #[Route('/changelog/{scope}', name: 'changelog_by_scope')]
   public function changelogByScope(Changelog $changelog, string $scope): Response
   {
       return $this->render('changelog.html.twig', [
           'content' => $changelog->render(['scope' => $scope])
       ]);
   }
   

3. CI/CD Integration: Generate changelogs in deployment pipelines:

   # .github/workflows/deploy.yml
   jobs:
     deploy:
       steps:
         - run: php bin/console git-changelog:generate --limit=50 --output=CHANGELOG.md
   

4. Planned Changes: Use plannedChangesFile.yml for upcoming work:

   # plannedChangesFile.yml
   - title: "API V2 Migration"
     description: "Deprecate V1 endpoints"
     ready: false
     type: refactor
   

5. Validation Rules: Enforce commit message standards via config:

   git_changelog_generator:
     validateMapping:
       'ROLE_*': ['<visibility footer>']
   

Gotchas and Tips

Pitfalls

1. Scope Mismatch:

   • Ensure commit messages match configured scopes (e.g., feature vs feat).
   • Debug with:

     php bin/console git-changelog:list-scopes
     

2. Visibility Defaults:

   • If visibility is missing in commit footers, the package uses the config default.
   • Override globally in git_changelog_generator.yaml:

     defaultVisibility: public
     

3. Twig Auto-escaping:

   • Use |raw in Twig to render HTML safely (e.g., Markdown converted to HTML).
   • Example:

     {{ changelogContent|raw }}
     

4. Git Repository Detection:

   • The package assumes the current directory is a Git repo. For submodules or custom paths:

     $changelog = $this->container->get(Changelog::class);
     $content = $changelog->render(['repoPath' => '/custom/path/to/repo']);
     

5. Planned Changes File:

   • If plannedChangesFile.yml is missing, the package silently skips rendering planned changes.
   • Explicitly check for its existence:

     if (file_exists($this->getParameter('planned_changes_file'))) {
         // Render planned changes
     }
     

Debugging

1. Dry Run: Use the console command to preview changes:

   php bin/console git-changelog:generate --dry-run
   

2. Log Commit Parsing: Enable debug mode in config:

   git_changelog_generator:
     debug: true
   

   Check logs for parsed commit metadata.

3. Commit Message Parsing:

   • Validate footers with regex:

     ^(title|description|visibility|v): .+$
     

   • Use git log --pretty=format:"%B" to inspect raw commit messages.

Extension Points

1. Custom Renderers: Extend the Changelog service to modify output:

   // src/Service/CustomChangelogRenderer.php
   use AlessandroPodo\GitChangelogGenerator\Service\Changelog\Changelog;
   
   class CustomChangelogRenderer extends Changelog
   {
       public function render(array $options = []): string
       {
           $content = parent::render($options);
           return $this->addCustomFooter($content);
       }
   
       private function addCustomFooter(string $content): string
       {
           return $content . "\n\n---\nGenerated by Custom System";
       }
   }
   

   Bind it in services.yaml:

   services:
       AlessandroPodo\GitChangelogGenerator\Service\Changelog\Changelog:
           alias: App\Service\CustomChangelogRenderer
   

2. Event Listeners: Trigger actions on changelog generation (e.g., notify Slack):

   // src/EventListener/ChangelogGeneratedListener.php
   use AlessandroPodo\GitChangelogGenerator\Event\ChangelogGeneratedEvent;
   
   class ChangelogGeneratedListener
   {
       public function onChangelogGenerated(ChangelogGeneratedEvent $event): void
       {
           $this->notifySlack($event->getContent());
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\ChangelogGeneratedListener:
           tags:
               - { name: kernel.event_listener, event: git_changelog.generated, method: onChangelogGenerated }
   

3. Dynamic Scopes: Fetch scopes from an external source (e.g., database):

   // src/Service/DynamicScopeProvider.php
   class DynamicScopeProvider
   {
       public function getScopes(): array
       {
           return $this->entityManager->getRepository(Scope::class)->findAll();
       }
   }
   

   Override the Changelog service to use the provider.

4. Markdown Customization: Use a templating engine (e.g., Twig) to transform raw output:

   {# templates/changelog/markdown.html.twig #}
   {% for entry in changelogEntries %}
       ## {{ entry.title }}
   
       {{ entry.description }}
   
       **Scope**: {{ entry.scope }}
       **Visibility**: {{ entry.visibility }}
   {% endfor %}