Spatie Version Control Guidelines

Overview

Apply Spatie's Git and version control conventions for consistent repository management.

When to Activate

• Activate this skill when creating commits, branches, or pull requests.
• Activate this skill when naming new repositories.
• Activate this skill when deciding on branching or merging strategies.

Scope

• In scope: Git operations, repository naming, branch naming, commit messages, merge strategies.
• Out of scope: Code style, deployment pipelines, CI/CD configuration.

Repository Naming

Site source code

Use the main domain name in lowercase, without www:

• Good: spatie.be
• Bad: https://www.spatie.be, www.spatie.be, Spatie.be

Subdomains

Include the subdomain in the repo name:

• Good: guidelines.spatie.be
• Bad: spatie.be-guidelines

Packages and other projects

Use kebab-case:

• Good: laravel-backup, spoon
• Bad: LaravelBackup, Spoon

Branches

Initial development

• Maintain main and develop branches.
• Commit through develop, not directly to main.
• Feature branches are optional; if used, branch from develop.

Live projects

• Delete the develop branch.
• All commits to main must come through feature branches.
• Prefer squashing commits on merge.

Branch naming

• Use lowercase letters and hyphens only.
• Good: feature-mailchimp, fix-deliverycosts, updates-june-2016
• Bad: feature/mailchimp, random-things, develop

Commits

Message format

• Always use present tense.
• Good: Update deps, Fix vat calculation in delivery costs
• Bad: wip, commit, a lot, solid

Granularity

• Prefer small, focused commits over large ones.
• Use git add -p for interactive staging to create granular commits.

Merging

• Rebase regularly to reduce merge conflicts.
• For deploying feature branches: use git merge <branch> --squash.
• If push is denied: use git rebase (not merge).

Pull Requests

• Optional but useful for peer review, merge validation, and historical reference.

---

Source: https://spatie.be/guidelines/version-control