Skip to main content

Git Workflow

Overview​

Our team follows a structured Git workflow to ensure code quality, maintainability, and collaboration. This document outlines our agreed-upon Git practices and conventions.

Branch Structure​

Main Branches​

  • main: Production-ready code, always deployable. Developers do not work directly on this branch. Changes from staging are automatically deployed to main via Laravel Forge at scheduled times.
  • staging: Pre-production testing environment. Hotfixes are branched from and merged back to this branch.
  • develop: Integration branch for features. Regular development work is branched from and merged back to this branch.

Branch Workflow​

  • Regular Development: Developers create branches from develop and push changes back to develop via pull requests.
  • Hotfixes: For critical issues, developers create branches from staging and push changes back to staging via pull requests.
  • Cherry-picking: The CTO is responsible for cherry-picking changes between staging and develop branches to keep them in sync.

Supporting Branches​

  • feature/[feature-name]: New features or enhancements
  • fix/[bug-description]: Non-critical bug fixes
  • hotfix/[hotfix-description]: Critical production fixes
  • change/[description]: Changes to existing functionality
  • improvement/[description]: Improvements to existing features
  • update/[description]: Updates to dependencies or configurations
  • SDK/[description]: SDK-related changes

Branch Naming Conventions​

Strict Enforcement

Branch names that do not follow these conventions will result in immediate closure of pull requests.

Branch names must consist of two parts separated by a forward slash:

  1. Type: Indicates the type of work being done
  2. Description: Describes the actual work
(hotfix|fix|change|feature|improvement|SDK|update)/what-we-do

The description part must follow slug conventions (lowercase with hyphens for word separation).

Valid Examples:

  • hotfix/mass-notif
  • feature/user-authentication
  • fix/login-validation
  • change/payment-flow
  • improvement/dashboard-performance
  • SDK/client-update
  • update/dependencies

Invalid Examples:

  • bug/login-issue (incorrect type)
  • feature_user_auth (incorrect separator)
  • hotfix/Mass-Notification (incorrect casing)

Commit Guidelines​

Commit Message Format​

We follow a structured commit message format:

[type]: Short summary (50 chars or less)

Detailed explanation if necessary. Wrap at 72 characters.
Explain what and why, not how (the code shows that).

Fixes #123

Commit Types​

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Formatting changes (white-space, formatting, etc.)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • test: Adding or updating tests
  • chore: Changes to build process or auxiliary tools
  • perf: Performance improvements

Commit Best Practices​

  • Make atomic commits (one logical change per commit)
  • Write descriptive commit messages
  • Reference issue numbers in commit messages
  • Don't commit commented-out code
  • Don't commit debug code or console logs
  • Don't commit generated files or dependencies

Code Quality Checks Before Committing​

Strict Enforcement

Before submitting code for review, all developers must run linters and formatters on their code.

Run the following command to check your latest commit:

php artisan code:run-all lastcommit

This command will:

  • Run all linters on your code
  • Format your code according to project standards
  • Check for common issues and coding standard violations

If the command reports any issues, fix them before creating a pull request. Pull requests with linting or formatting issues will be rejected.

Pull Request Process​

Creating Pull Requests​

  1. Create a branch from the appropriate base branch (develop for regular work, staging for hotfixes)
  2. Make your changes in small, logical commits
  3. Run linters and formatters (php artisan code:run-all lastcommit)
  4. Push your branch to the remote repository
  5. Create a pull request with a descriptive title and description
  6. Fill out the PR template completely
  7. Assign reviewers (minimum 2, including CTO)
  8. Link related issues

PR Description Requirements​

Strict Enforcement

Pull requests that do not follow these description guidelines will not be merged.

PR descriptions must be comprehensive and self-contained:

  • Do not reference tasks, Sentry, or Telescope in lieu of proper descriptions
  • Write complete explanations of what changes were made and why
  • For package updates (especially client-side SDK updates), explicitly list all changes in the new version

Required PR Description Structure​

Strict Enforcement

Pull requests that do not follow this exact structure will be closed immediately. You will need to create a new PR with the correct structure.

All pull request descriptions must follow this exact structure:

Related Task: (Trello task URL)
Description: (Clear explanation of what changes were made)
Test Checklist:
- First item
- Second item
- Third item

In the test checklist, include items that:

  • Need to be tested after this PR is merged
  • Are directly related to the task
  • May be affected by side effects of your changes

PR Template​

## Related Task
[Insert Trello task URL here]

## Description
[Explain what changes you've made - clearly and in detail]

## Test Checklist
- [First item that needs testing]
- [Second item that needs testing]
- [Third item that needs testing]

## Package Updates (if applicable)
- [Package Name] updated from [old version] to [new version]
- Changes in this version:
  - [List all significant changes in the new version]
  - [Include any breaking changes]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## How Has This Been Tested?
[Describe the testing approach]

## Checklist
- [ ] My code follows the project's coding standards
- [ ] I have added tests that prove my fix/feature works
- [ ] I have updated documentation as needed
- [ ] All tests pass locally

Handling Conflicts and Unrelated Changes​

Strict Enforcement

Pull requests containing unrelated commits or files from other developers will not be merged.

When your branch contains unrelated changes:

  1. It is your responsibility to clean up your branch
  2. You may use rebase or merge techniques as you prefer
  3. The CTO will not assist with resolving these issues
  4. The problem must be 100% resolved before the PR will be merged
# Option 1: Using rebase to clean up your branch
git checkout develop  # or staging for hotfixes
git pull
git checkout your-branch
git rebase -i develop  # or staging for hotfixes
# In the interactive rebase, keep only your commits and drop others

# Option 2: Creating a clean branch
git checkout develop  # or staging for hotfixes
git pull
git checkout -b clean-branch-name
git cherry-pick <your-commit-hashes>
# Then create a new PR from the clean branch

Handling Conflicts​

When conflicts arise:

  1. Pull the latest changes from the base branch (develop or staging)
  2. Resolve conflicts locally
  3. Test thoroughly after conflict resolution
  4. Push the resolved changes
  5. Document complex conflict resolutions in the PR

Release Process​

Our Git release process:

  1. Changes are merged into the develop branch through the PR process
  2. The staging branch is updated with changes from develop (managed by CTO)
  3. Testing is performed on the staging environment
  4. At scheduled times, changes from staging are automatically deployed to main via Laravel Forge
  5. For hotfixes, changes are merged directly to staging and then cherry-picked to develop by the CTO

Git Hooks​

We use Git hooks to enforce quality:

  • pre-commit: Run linting and formatting
  • pre-push: Run tests
  • commit-msg: Validate commit message format

Continuous Integration​

Our CI pipeline runs on all pull requests:

  1. Build the project
  2. Run linting and static analysis
  3. Run unit and integration tests
  4. Generate code coverage reports
  5. Check for security vulnerabilities
  6. Build documentation

Git Best Practices​

  • Keep branches short-lived (1-2 weeks maximum)
  • Pull from the base branch regularly to minimize conflicts
  • Don't force push to shared branches
  • Use rebase to keep feature branches up-to-date
  • Write meaningful commit messages
  • Commit early and often
  • Review your own code before requesting reviews

Git Configuration​

Recommended Git configuration:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global core.editor "code --wait"
git config --global pull.rebase true
git config --global rebase.autoStash true

Troubleshooting Common Issues​

Resolving Merge Conflicts​

# Update your branch with the latest changes
git checkout develop  # or staging for hotfixes
git pull
git checkout your-branch
git rebase develop  # or staging for hotfixes

# Resolve conflicts and continue
git add .
git rebase --continue

Undoing Local Changes​

# Discard all local changes
git reset --hard HEAD

# Discard changes to a specific file
git checkout -- path/to/file

# Undo the last commit but keep changes
git reset --soft HEAD~1
Last updated on by Behnam Moradi