Version Control

Git Workflow

A well-defined Git workflow ensures code quality, collaboration, and traceability. Follow these steps for all Laravel projects:

Branching Strategy

• Feature Branches: For new features. Name as feature/<descriptive-name>. Example: feature/user-authentication.
• Bugfix Branches: For bug fixes. Name as bugfix/<descriptive-name>. Example: bugfix/login-error.
• Release Branches: For preparing releases. Name as release/v1.0.
• Hotfix Branches: For urgent production fixes. Name as hotfix/<descriptive-name>.
• Main Branch: Production-ready code. Only merge after review and testing.
• Develop Branch: Main working branch for integration and testing.

Pull Requests & Code Review

• Create a pull request (PR) for every merge into main or develop.
• Assign at least one reviewer. Two reviewers recommended for critical changes.
• Use CI/CD to run tests and checks before merging.
• Address all review comments before merging.
• Delete feature/bugfix branches after merging to keep the repository clean.

Merging Guidelines

• Always merge using the pull request workflow.
• Use squash and merge for combining many small commits.
• Avoid force-pushing to shared branches.

Branch Naming Conventions

Use descriptive and consistent branch names:

• Good: feature/user-authentication, bugfix/login-error, release/v1.0, hotfix/payment-issue
• Bad: feature, fix, release1

Commit Messages

Commit messages should be clear, concise, and follow a convention:

• Use present tense: add, fix, update
• Keep under 50 characters if possible
• Format: type: short description
• Example: feat: implement user authentication

Type Prefixes

• feat: new features
• fix: bug fixes
• style: styling changes
• docs: documentation updates
• test: adding/updating tests
• refactor: code refactoring
• chore: miscellaneous tasks

Breaking Changes

If a commit introduces a breaking change, add BREAKING CHANGE: in the message.

Tagging and Versioning

• Tag releases using Semantic Versioning: MAJOR.MINOR.PATCH (e.g., v1.0.0)
• Document release notes for each tag

Example Workflow

1. Create a feature branch: git checkout -b feature/user-authentication
2. Commit changes: git commit -m "feat: implement user authentication"
3. Push branch: git push origin feature/user-authentication
4. Create a pull request and request review
5. Merge after approval and CI/CD checks
6. Delete branch after merge

Best Practices

• Commit frequently and in small increments
• Write descriptive commit messages
• Use pull requests for all merges
• Review code for quality, security, and performance
• Tag releases and maintain release notes