Branch Alias Validation Laravel Package

Product Decisions This Supports

• Enforcing Git Workflow Discipline: Integrate into CI/CD pipelines to block merges of branches that haven’t advanced beyond the latest tag, ensuring alignment with semantic versioning (SemVer) and release cycles. This prevents "stale" branches from polluting main or develop.
• Reducing Release Blockers: Act as a preemptive check to catch version skew early, reducing last-minute fixes during deployments. Aligns with DevOps principles of "shift-left" validation.
• Build vs. Buy Decision: Buy—this is a lightweight, niche solution that avoids reinventing Git logic. Ideal for teams using Laravel/PHP with Composer, as it integrates seamlessly without requiring custom development.
• Roadmap for Scalability:
  • Phase 1: Enforce branch-tag alignment in CI/CD (e.g., GitHub Actions, GitLab CI).
  • Phase 2: Extend to auto-generate tags from branch commits (e.g., release/1.2.x → v1.2.0) using Git hooks or Laravel events.
  • Phase 3: Integrate with Laravel’s deployment tools (e.g., Envoyer, Forge) to validate branches before release.
• Use Cases:
  • Open-Source Projects: Enforce consistency across contributors using shared branch conventions.
  • Enterprise PHP Apps: Prevent "rogue" branches from breaking release workflows, especially in monorepos or modular Laravel applications.
  • Laravel-Specific: Validate feature branches in monorepos (e.g., packages/*) or during git flow-like workflows.

When to Consider This Package

• Adopt If:
  • Your team uses Git tags for releases (e.g., v1.0.0, v2.3.4) and relies on branch aliases (e.g., feature/, release/, hotfix/) for workflow organization.
  • You need preventative validation to catch misaligned branches before they reach main or develop, rather than relying on post-release checks.
  • Your CI/CD pipeline lacks native Git branch-tag validation (e.g., GitHub Actions, GitLab CI without custom scripts).
  • You’re using Laravel/PHP and manage dependencies via Composer, making integration frictionless.
  • Your team follows semantic versioning (SemVer) and wants to enforce version consistency across branches.
• Look Elsewhere If:
  • Your workflow relies on continuous deployment without explicit tags (e.g., commit SHA-based releases).
  • You use trunk-based development with no long-lived branches or tagging discipline.
  • You need advanced Git logic (e.g., merge conflict detection, cross-repository validation)—consider GitHub’s API, LibGit2, or custom scripts.
  • Your team prefers GUI tools (e.g., GitKraken, Sourcetree) over CLI validation, though this can still be integrated into CI.
  • You require programmatic access to validation results (e.g., API responses) and the package’s CLI output isn’t sufficient.

How to Pitch It (Stakeholders)

For Executives: "This package adds a lightweight but critical layer of quality control to our release process. By ensuring every branch is ahead of the latest tag, we eliminate the risk of merging ‘stale’ code into main or develop, which could lead to version conflicts or deployment failures. For example, if a release/2.0 branch hasn’t advanced past v1.5.0 while main is at v2.1.0, this tool will block the merge—saving hours of debugging and potential downtime. The setup is minimal (a single Composer package and a CI step), with zero operational overhead, and it aligns perfectly with our SemVer and Git flow practices."

For Engineering (Tech Leads/Architects): *"We’re proposing to add phpcq/branch-alias-validation to our toolchain to:

1. Validate branches pre-merge: Fail fast if a branch lags behind the latest tag (e.g., feature/payment stuck at v1.2.0 while main is at v1.3.0).
2. Integrate with CI/CD: Run ./vendor/bin/validate-branch-alias.php as a required step in GitHub Actions/GitLab CI for feature/* and release/* branches.
3. Leverage Laravel’s ecosystem: Since it’s PHP-based, it integrates seamlessly with Composer and can be wrapped in a custom Artisan command for local development. Effort: ~1 hour to configure. Impact: Catches 30–50% of potential release blockers before they reach QA, with minimal maintenance overhead. This is a ‘no-brainer’ for teams using Git tags and branch aliases."*

For Developers: *"This tool acts as a Git branch gatekeeper. Before you merge feature/x into develop, it checks:

• Is this branch’s latest commit newer than the last tag (e.g., v1.2.0)?
• If not, it fails with a clear error: ‘Branch feature/x is behind v1.2.0—update or create a new tag.’ How to use:

1. Add to composer.json under require-dev.
2. Run ./vendor/bin/validate-branch-alias.php locally or in CI. Why now? It’s the missing link between ‘code complete’ and ‘release ready,’ ensuring we don’t accidentally merge branches that could break our versioning or deployment pipelines. Think of it as spellcheck for Git workflows."*

For DevOps/SRE: *"This package addresses a common pain point in Git workflows: branch drift. By validating that all branches are ahead of the latest tag, we:

• Reduce the risk of version skew in releases.
• Catch stale branches before they pollute main or develop.
• Align with our SemVer and Git flow practices without adding complexity. Integration:
• Add to CI as a gated step (e.g., fails pipeline if validation fails).
• Optionally wrap in a custom Git hook (e.g., pre-push) for local enforcement. No changes to infrastructure required—just a Composer package and a CI step."*