Git Workflow We follow a feature branch workflow with pull request reviews before merging to the main branch.
Branch Naming Convention Use descriptive branch names that follow this pattern:
< type > / < ticket-id > - < short-description >
Types:
feature/ - New features or enhancementsfix/ - Bug fixeshotfix/ - Urgent production fixesrefactor/ - Code refactoringdocs/ - Documentation updatestest/ - Test additions or modifications
Examples: feature/AUTH-123-oauth-integration fix/UI-456-button-alignment refactor/PERF-789-optimize-queries
Include the ticket or issue number in your branch name to maintain traceability.
Development Process
Create a New Branch
Always branch from the latest main branch: git checkout main git pull origin main git checkout -b feature/NEW-123-user-profile
Make Your Changes
Develop your feature with frequent, atomic commits: # Make changes to files git add . git commit -m "feat: add user profile component" # Continue developing git add . git commit -m "feat: add profile edit functionality"
Keep Branch Updated
Regularly sync your branch with main to avoid conflicts: git fetch origin git rebase origin/main
If you’ve already pushed your branch, use git push --force-with-lease after rebasing.
Run Tests and Linting
Ensure all checks pass before pushing: npm run lint npm run type-check npm run test npm run build
Push Your Branch
Push your branch to the remote repository: git push origin feature/NEW-123-user-profile
Create a Pull Request
Open a pull request on GitHub/GitLab with a descriptive title and description.
Commit Message Convention We use Conventional Commits for clear and consistent commit history.
<type>(<scope>): <subject> <body> <footer>
Types
feat - A new featurefix - A bug fixdocs - Documentation changesstyle - Code style changes (formatting, semicolons, etc.)refactor - Code refactoring without changing functionalityperf - Performance improvementstest - Adding or updating testschore - Maintenance tasks, dependencies, build processci - CI/CD configuration changes
Examples feat(auth ): implement OAuth2 login flow fix(ui ): correct button alignment on mobile devices docs: update README with setup instructions refactor(api ): simplify user data fetching logic perf(images ): lazy load images below the fold test ( auth ): add unit tests for login component
When introducing breaking changes, add BREAKING CHANGE: in the footer: feat(api): change user endpoint response format BREAKING CHANGE: User endpoint now returns nested profile object instead of flat structure. Update client code accordingly.
Pull Request Guidelines PR Title Use the same convention as commit messages:
feat(auth): implement OAuth2 login flow
PR Description Template Provide comprehensive context in your PR description:
## Description Brief description of what this PR does. ## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Breaking change - [ ] Documentation update ## Changes Made - Added OAuth2 authentication flow - Created login component with social providers - Updated authentication context ## Testing - [ ] Unit tests added/updated - [ ] Integration tests added/updated - [ ] Manual testing completed ## Screenshots (if applicable) [Add screenshots or GIFs demonstrating the changes] ## Related Issues Closes #123 Related to #456 ## Checklist - [ ] Code follows project style guidelines - [ ] Self-review completed - [ ] Comments added for complex logic - [ ] Documentation updated - [ ] No new warnings generated
PR Size Guidelines Keep PRs small and focused. Large PRs are harder to review and more likely to introduce bugs.
Ideal PR sizes:
Small: < 200 lines changed
Medium: 200-400 lines changed
Large: 400-800 lines changed
Too Large: > 800 lines (consider breaking it up)
Code Review Process For Authors
Self-Review First
Review your own PR before requesting reviews. Check for:
Code quality and readability
Unnecessary console logs or debug code
Proper error handling
Test coverage
Request Reviews
Assign appropriate reviewers based on the changes:
At least one senior developer
Domain experts if touching critical areas
Address Feedback
Respond to all comments and make requested changes: # Make changes based on feedback git add . git commit -m "refactor: address PR feedback" git push origin feature/NEW-123-user-profile
Resolve Conversations
Mark conversations as resolved once addressed.
For Reviewers Provide constructive, actionable feedback:
Good feedback: Consider extracting this logic into a separate hook for better reusability: [code suggestion] This would make it easier to test and reuse in other components.
Poor feedback: Review Checklist Continuous Integration All PRs must pass CI checks before merging:
Automated Checks # .github/workflows/ci.yml name : CI on : [ pull_request ] jobs : test : runs-on : ubuntu-latest steps : - uses : actions/checkout@v3 - name : Setup Node uses : actions/setup-node@v3 with : node-version : '18' - name : Install dependencies run : npm ci - name : Lint run : npm run lint - name : Type check run : npm run type-check - name : Test run : npm run test:ci - name : Build run : npm run build
CI failures should be addressed immediately. Don’t request reviews until all checks pass.
Merging Strategy We use squash and merge for most PRs to keep the main branch history clean.
When to Use Each Strategy
Squash and Merge (Default)
Use for feature branches with multiple commits: # Multiple commits become one feat: add user profile functionality - Add profile component - Add edit functionality - Add validation
Use when commits are already well-organized and atomic: feat: add profile component feat: add profile edit functionality test : add profile component tests
Rarely used, only for combining long-lived branches: Merge branch 'release/v2.0' into main
Conflict Resolution When encountering merge conflicts:
Update Your Branch
git fetch origin git rebase origin/main
Resolve Conflicts
Open conflicted files and resolve markers: <<<<<<< HEAD const userName = user.name; ======= const userName = user.fullName; >>>>>>> feature/NEW-123
Choose the correct resolution: const userName = user . fullName ;
Continue Rebase
git add . git rebase --continue
Force Push
git push --force-with-lease origin feature/NEW-123-user-profile
Never use git push --force without --force-with-lease, as it can overwrite others’ work.
Release Process For production releases:
Create a release branch from main
Update version numbers and changelog
Create a release PR
After approval, merge and tag the release
Deploy to production
# Create release branch git checkout -b release/v1.2.0 main # Update version npm version minor # Tag release git tag -a v1.2.0 -m "Release v1.2.0" git push origin v1.2.0