Maintaining Forked Laravel Packages: Release Workflow

Sometimes you need to fork a Laravel package to fix bugs or add features the maintainer won’t merge. Here’s a clean workflow for maintaining your fork while keeping your app’s composer dependencies sane.

The Scenario

You’re using a third-party admin panel package, but it has bugs. The upstream maintainer is inactive. You need to fix it yourself and use the fixes in your app.

Fork Workflow

# 1. Fork the package on GitHub
# github.com/original-author/admin-package → github.com/your-org/admin-package

# 2. Create a branch for your fixes
git checkout -b fix/column-filters
# ... make your changes ...
git push origin fix/column-filters

# 3. Create PR in YOUR fork (not upstream)
# This gives you a place to review and discuss changes internally

# 4. After PR approved, merge to your fork's master
git checkout master
git merge fix/column-filters
git push origin master

# 5. Tag a release
git tag v2.1.5
git push origin v2.1.5

Composer Configuration

In your app’s composer.json, point to your fork:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/your-org/admin-package"
        }
    ],
    "require": {
        "original-author/admin-package": "^2.1"
    }
}

Composer will automatically use your fork when you run composer update, because it sees a newer version (v2.1.5) in your repository.

Version Constraints

Before tagging, check if your app’s constraint will auto-update:

• "^2.1" will pick up v2.1.5 automatically ✅
• "~2.1.0" will pick up v2.1.5 automatically ✅
• "2.1.0" exact version won’t auto-update ❌

If using exact versions, you’ll need to manually bump the constraint in composer.json.

Testing Before Release

Before tagging, test your changes in staging:

1. Update composer to use your fork’s master branch (pre-tag)
2. Test the specific admin pages that use the package
3. Verify filters, columns, and any features you touched
4. Only then tag the release and update production

Documentation

In your PR description, document:

• What bug you fixed
• Which pages/features to test in staging
• Any breaking changes

This helps your team review and deploy confidently, especially when the original package documentation is lacking.

When to Fork vs. Patch

Fork when:

• The upstream is abandoned
• Your fixes are app-specific and won’t be accepted upstream
• You need long-term control over the package

Use Composer patches (cweagans/composer-patches) when:

• The fix is small and temporary
• You expect upstream to merge it soon
• You don’t want to maintain a full fork