Git Workflow Standards for Frontend Teams
Practical standards for branch naming, commit messages, and pull request descriptions that make code review faster and git history actually useful.
Git is not just version control — it's communication. Every commit message, branch name, and pull request description is a message to your future self and your teammates. Treat it that way. ## Branch Naming Branches should encode their purpose: ``` feature/user-management fix/login-validation hotfix/production-auth-error refactor/dashboard-layout chore/update-dependencies ``` The prefix (`feature`, `fix`, `hotfix`, `refactor`, `chore`) immediately communicates the nature of the work. A reviewer scanning branch names can triage pull requests before even opening them. ## Commit Messages Use the conventional commits format: `type: message` ``` feat: add user management page fix: handle login error response refactor: simplify dashboard layout style: adjust button spacing chore: update dependencies docs: add API integration guide test: add unit tests for formatDate ``` A good commit message explains the *what*, not the *how*. The code already shows the how. The message should tell a future developer why this change existed and what problem it solved. **The rules:** - One commit, one change. Don't bundle a bug fix with a refactor. - Never commit `.env` files. - Never commit `console.log` debug statements. - Never commit build artifacts unless required. ## Pull Request Descriptions A PR description is documentation. It should tell a reviewer what changed, why, and how to test it: ``` Title: [Feature] Add user management page Description: Adds the user management section with list, create, edit, and delete functionality. Changes: - Added user list table with pagination and search - Added create/edit form with Zod validation - Added delete confirmation dialog - Connected to /api/users endpoints Testing: - Create a new user via the form - Edit an existing user - Delete a user and confirm via dialog - Verify empty state when no users exist ``` ## The Pre-Merge Checklist Before any PR is merged, verify: - [ ] No TypeScript errors (`tsc --noEmit`) - [ ] No lint errors (`eslint`) - [ ] Build passes (`npm run build`) - [ ] No console errors in browser - [ ] Loading, empty, and error states present - [ ] No hardcoded credentials - [ ] Responsive layout checked This checklist transforms code review from a bug hunt into a quality gate. When developers trust that these checks pass before a PR lands, the review can focus on architecture and logic instead of style and typos.
