Skip to main content

Git Workflow & Best Practices

Git workflow, branching strategy, and contribution process for ZÈYA platform.

🌿 Branching Strategy​

Main Branches​

  • main - Production-ready code
  • staging - Staging environment branch

Feature Branches​

[!IMPORTANT] Make sure that branch names are prefixed with the issue ID from linear. See examples below.

Create feature branches from staging:

git checkout -b feature/ZEY-300-feature-name

Naming Convention:

  • feature/ZEY-300-feature-name - New features
  • fix/ZEY-300-bug-description - Bug fixes
  • refactor/ZEY-300-component-name - Code refactoring
  • docs/ZEY-300-documentation-update - Documentation updates
  • test/ZEY-300-test-description - Adding tests
  • hotfix/ZEY-300-urgent-fix - quick fixes that have to be deployed to producton ASAP.

Branch Protection​

  • main & staging branches are protected
  • Requires pull request review
  • Requires passing CI checks
  • No direct commits to main or staging

Hot Fixes​

Whenever we want to deploy urgent fixes to production we simply checkout from the main branch and use the prefix hotfix/, commit changes and create a PR with the target branch being main.

[!NOTE] Make sure to update the staging branch from main when the hotfix is merged into main.

📝 Commit Messages​

Commit Message Format​

Use conventional commit format:

<type>(<scope>): <subject>

<body>

<footer>

Commit Types​

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes (formatting, etc.)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks
  • perf: - Performance improvements
  • ci: - CI/CD changes

Examples​

feat(api): add product search endpoint

Add new endpoint for searching products with filters
and pagination support.

Closes #123

fix(mobile): resolve authentication token refresh issue

The token refresh was failing on app restart. Fixed
by improving token storage mechanism.

docs(admin): update API integration guide

Add examples for error handling and retry logic.

🔄 Pull Request Process​

Creating a Pull Request​

  1. Create Feature Branch

    git checkout -b feature/my-feature

  2. Make Changes

    • Write code following standards
    • Add tests if applicable
    • Update documentation

  3. Commit Changes

    git add .
    git commit -m "feat: add new feature"

  4. Push Branch

    git push origin feature/my-feature

  5. Create Pull Request

    • Use descriptive title
    • Add detailed description
    • Link related issues
    • Request reviewers

Pull Request Template​

## Description
Brief description of changes

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

## Testing
- [ ] Tests added/updated
- [ ] Manual testing completed
- [ ] Tested on iOS/Android (for mobile)
- [ ] Tested in browser (for admin)

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests pass

Review Process​

  1. Code Review

    • At least one approval required
    • Address review comments
    • Update PR if needed

  2. CI Checks

    • All CI checks must pass
    • Fix any failing tests
    • Resolve linting errors

  3. Merge

    • Squash and merge (preferred)
    • Or merge commit
    • Delete branch after merge

🚫 What Not to Commit​

Never Commit​

  • .env files
  • node_modules/
  • vendor/ (PHP)
  • Build artifacts (.next/, dist/)
  • IDE configuration files (unless team standard)
  • Personal notes or TODOs
  • Sensitive credentials
  • Large binary files

Use .gitignore​

Ensure .gitignore includes:

.env
.env.local
node_modules/
vendor/
.next/
dist/
build/
*.log
.DS_Store

🔀 Merging Strategies​

Squash and Merge (Preferred)​

  • Combines all commits into one
  • Cleaner git history
  • Easier to revert if needed

Merge Commit​

  • Preserves commit history
  • Shows feature development process
  • Use for complex features

Rebase (Advanced)​

  • Linear history
  • Requires force push
  • Use carefully on shared branches

📋 Pre-Commit Checklist​

Before committing:

  • Code follows style guidelines
  • Tests pass (if applicable)
  • No console.logs left
  • Documentation updated
  • No sensitive data committed
  • .gitignore is correct
  • Commit message follows convention

🔍 Code Review Guidelines​

For Authors​

  • Keep PRs small and focused
  • Write clear commit messages
  • Respond to review comments promptly
  • Be open to feedback

For Reviewers​

  • Review within 24-48 hours
  • Be constructive and respectful
  • Check for:
    • Code quality
    • Security issues
    • Performance concerns
    • Test coverage
    • Documentation updates

🏷️ Tagging & Releases​

Version Tags​

Tag releases with semantic versioning:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Semantic Versioning​

  • MAJOR.MINOR.PATCH
  • MAJOR - Breaking changes
  • MINOR - New features (backward compatible)
  • PATCH - Bug fixes

🔄 Syncing with Main​

Keep Branch Updated​

# Fetch latest changes
git fetch origin

# Rebase on main
git checkout feature/my-feature
git rebase origin/main

# Or merge main into feature
git merge origin/main

🆘 Common Git Issues​

Undo Last Commit​

# Keep changes
git reset --soft HEAD~1

# Discard changes
git reset --hard HEAD~1

Change Last Commit Message​

git commit --amend -m "New message"

Remove File from Git​

# Remove from Git but keep file
git rm --cached file.txt

# Remove from Git and delete file
git rm file.txt