Changelog Linker Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require symplify/changelog-linker --dev
   

   Register the package in composer.json under extra:

   {
       "extra": {
           "symplify": {
               "changelog-linker": {
                   "file": "CHANGELOG.md",
                   "format": "markdown"
               }
           }
       }
   }
   

2. First Use Case Run the CLI command to generate links in your CHANGELOG.md:

   vendor/bin/changelog-linker
   

   This will automatically link:

   • GitHub issues/PRs (e.g., #123 → [#123](https://github.com/your/repo/issues/123)).
   • Semantic version tags (e.g., v1.0.0 → [v1.0.0](https://github.com/your/repo/releases/tag/v1.0.0)).

3. Where to Look First

   • Configuration: Check composer.json under extra.symplify.changelog-linker.
   • CLI Help: Run vendor/bin/changelog-linker --help for options.
   • Default Rules: Review Symplify’s docs for supported patterns (e.g., #123, GH-456, v1.2.3).

Implementation Patterns

Usage Patterns

1. Automated CI Integration Add to your CI pipeline (e.g., GitHub Actions) to auto-link changelogs post-release:

   - name: Link CHANGELOG
     run: vendor/bin/changelog-linker
   

   Trigger after git tag or git push.

2. Custom Link Formats Extend via extra.symplify.changelog-linker:

   {
       "custom_patterns": [
           {
               "pattern": "/\\b(?:fix|feat)\\/([a-f0-9]+)\\b/",
               "replacement": "[\\0](https://your-tracker.com/issues/\\1)"
           }
       ]
   }
   

3. Dry Run Mode Test changes without modifying files:

   vendor/bin/changelog-linker --dry-run
   

4. Multi-File Support Process additional changelog files (e.g., UPGRADING.md):

   {
       "files": ["CHANGELOG.md", "UPGRADING.md"]
   }
   

Workflows

• Pre-Release Workflow:

  1. Update CHANGELOG.md manually.
  2. Run changelog-linker to auto-link references.
  3. Commit the linked changelog.

• Post-Merge Workflow: Use Git hooks (e.g., post-merge) to auto-link changelogs when merging PRs.

Integration Tips

• Laravel Artisan Command: Create a custom Artisan command to wrap changelog-linker:

  // app/Console/Commands/LinkChangelog.php
  namespace App\Console\Commands;
  use Symfony\Component\Process\Process;
  class LinkChangelog extends Command {
      protected function handle() {
          $process = new Process(['vendor/bin/changelog-linker']);
          $process->run();
          $this->info($process->getOutput());
      }
  }
  

  Register in app/Console/Kernel.php and run via php artisan changelog:link.

• GitHub Actions Example:

  name: Changelog Linker
  on: [push]
  jobs:
    link-changelog:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - run: composer install --dev
        - run: vendor/bin/changelog-linker
        - uses: stefanzweifel/git-auto-commit-action@v4
          with:
            commit_message: "chore: auto-link CHANGELOG.md"
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity in GitHub Links

   • GitHub URLs are case-sensitive for repos (e.g., github.com/YourRepo vs. github.com/yourrepo).
   • Fix: Ensure extra.symplify.changelog-linker.repo matches your repo’s exact case.

2. Custom Patterns Overwriting Defaults

   • Incorrect regex in custom_patterns may break existing links.
   • Tip: Test with --dry-run first.

3. Non-Markdown Files

   • The package defaults to Markdown. For non-MD files (e.g., .txt), set "format": "plain".
   • Warning: Plaintext links may not render correctly in all contexts.

4. GitHub Enterprise/SSH URLs

   • Default GitHub links use https://github.com. For Enterprise or SSH:

     {
         "github_url": "https://github.yourcompany.com",
         "use_ssh": true
     }
     

5. Performance with Large CHANGELOGs

   • Processing 1000+ entries may slow down CI.
   • Optimization: Run in a separate job or cache the output.

Debugging

• Verbose Output:

  vendor/bin/changelog-linker -v
  

  Shows skipped entries and regex matches.

• Log File: Redirect output to a file for debugging:

  vendor/bin/changelog-linker > changelog-linker.log 2>&1
  

• Common Errors:

  • Invalid repo URL: Verify repo in config matches your Git remote.
  • No matches found: Check if your changelog uses supported patterns (e.g., #123).

Config Quirks

1. Dynamic Repo Detection The package auto-detects the repo from .git/config. Override with:

   {
       "repo": "your-org/your-repo"
   }
   

2. Branch-Specific Links Link to branch-specific issues/PRs:

   {
       "branch": "dev",
       "github_url": "https://github.com/your-org/your-repo/issues/{issue}?branch={branch}"
   }
   

3. Excluding Sections Skip certain changelog sections (e.g., ## Uncategorized):

   {
       "exclude_sections": ["Uncategorized"]
   }
   

Extension Points

1. Custom Replacement Logic Extend via a PHP service provider:

   // app/Providers/ChangelogLinkerServiceProvider.php
   namespace App\Providers;
   use Symplify\ChangelogLinker\ValueObject\Configuration;
   class ChangelogLinkerServiceProvider extends \Illuminate\Support\ServiceProvider {
       public function register() {
           $this->app->extend(Configuration::class, function ($config) {
               $config->addCustomPattern('/\b(?:BUG|TASK)-(\d+)\b/', '[\\0](https://jira.example.com/browse/\\1)');
               return $config;
           });
       }
   }
   

2. Post-Processing Hooks Use Laravel’s finished event to run additional logic after linking:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Symplify\ChangelogLinker\Application::class => [
           \App\Listeners\PostChangelogLink::class,
       ],
   ];
   

3. GitLab/Bitbucket Support Override the github_url template:

   {
       "github_url": "https://gitlab.com/{repo}/issues/{issue}",
       "use_ssh": false
   }